Get Roadie in your IDE with our new MCP Servers
Roadie
← Backstage Plugins Guides
Backstage Software Catalog logo

Backstage Software Catalog Plugin

Created by Spotify

Backstage Software Catalog is the system of record in Backstage. It tracks services, libraries, websites, APIs, and data pipelines, with clear ownership and metadata. The catalog plugin gives teams a searchable view, filters for kind, tags, and owner, and rich entity pages with about details, links, labels, relations, and optional docs and templates. It scales through providers that ingest metadata from source control, then keeps the catalog fresh on a schedule. This makes discovery easier and helps drive standardization across teams.

Many companies use the catalog to speed up work. Chicago Trading Company reports strong onboarding wins. As one engineer put it, Backstage made onboarding not scary because templates give a clear path and you are off and running.

QuintoAndar calls the Software Catalog a source of truth for every developer. It helped them highlight and unify the tools needed to build and run software without deep tool expertise.

Dynatrace uses Backstage as its central portal and links real time data into catalog entities. They note that centralizing artifacts and democratizing ownership reduced onboarding time for teams.

If you run a self hosted Backstage, this plugin is the place engineers will browse software, find owners, open docs and pipelines, and spot dependencies and health in one view.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the frontend package

If the package is missing from packages app package.json run

Copy 
yarn --cwd packages/app add @backstage/plugin-catalog

Add the catalog pages to your frontend routes

Open packages app src App.tsx and add the imports and routes

Copy 
// packages/app/src/App.tsx
import React from 'react';
import { createApp } from '@backstage/app-defaults';
import { FlatRoutes } from '@backstage/core-app-api';
import { Route } from 'react-router';
import {
  CatalogIndexPage,
  CatalogEntityPage,
} from '@backstage/plugin-catalog';
import { entityPage } from './components/catalog/EntityPage';

const app = createApp();

const routes = (
  <FlatRoutes>
    <Route path="/catalog" element={<CatalogIndexPage />} />
    <Route
      path="/catalog/:namespace/:kind/:name"
      element={<CatalogEntityPage />}
    >
      {entityPage}
    </Route>
  </FlatRoutes>
);

export default app.createRoot(() => routes);

Bind the catalog create route to Scaffolder

Open packages app src App.tsx and bind the external route

Copy 
// packages/app/src/App.tsx
import { createApp } from '@backstage/app-defaults';
import { catalogPlugin } from '@backstage/plugin-catalog';
import { scaffolderPlugin } from '@backstage/plugin-scaffolder';

const app = createApp({
  bindRoutes({ bind }) {
    bind(catalogPlugin.externalRoutes, {
      createComponent: scaffolderPlugin.routes.root,
    });
  },
});

Open packages app src components Root Root.tsx and add the item

Copy 
// packages/app/src/components/Root/Root.tsx
import React, { PropsWithChildren } from 'react';
import { SidebarPage, Sidebar, SidebarItem } from '@backstage/core-components';
import HomeIcon from '@material-ui/icons/Home';

export const Root = ({ children }: PropsWithChildren<{}>) => (
  <SidebarPage>
    <Sidebar>
      <SidebarItem icon={HomeIcon} to="catalog" text="Home" />
    </Sidebar>
    {children}
  </SidebarPage>
);

Optional add catalog cards to your custom entity page

If you keep a custom EntityPage you can show cards from the plugin. Open packages app src components catalog EntityPage.tsx and add the card

Copy 
// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import Grid from '@material-ui/core/Grid';
import {
  EntityAboutCard,
} from '@backstage/plugin-catalog';

export const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    <Grid item xs={12} md={6}>
      <EntityAboutCard variant="gridItem" />
    </Grid>
  </Grid>
);

// export entityPage as in your app template and include overviewContent there

Install the backend package

If the package is missing from packages backend package.json run

Copy 
yarn --cwd packages/backend add @backstage/plugin-catalog-backend

Wire the backend plugin in the new backend system

Open packages backend src index.ts and add the plugin

Copy 
// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

backend.add(import('@backstage/plugin-catalog-backend'));

// add other plugins here

backend.start();

Wire the backend plugin in the old backend system

Create packages backend src plugins catalog.ts with the router. Use the template from create app. Example

Copy 
// packages/backend/src/plugins/catalog.ts
import { createRouter } from '@backstage/plugin-catalog-backend';
import { Router } from 'express';
import type { PluginEnvironment } from '../types';

export default async function createPlugin(env: PluginEnvironment): Promise<Router> {
  return await createRouter({
    logger: env.logger,
    config: env.config,
    database: env.database,
    discovery: env.discovery,
    tokenManager: env.tokenManager,
    permissions: env.permissions,
    identity: env.identity,
  });
}

Then register the router in packages backend src index.ts

Copy 
// packages/backend/src/index.ts
import { Router } from 'express';
import { useHotMemoize } from '@backstage/backend-common';
import { notFoundHandler } from '@backstage/backend-common';
import catalog from './plugins/catalog';

// inside your main bootstrap function
const apiRouter = Router();

const catalogEnv = useHotMemoize(module, () => createEnv('catalog'));
apiRouter.use('/catalog', await catalog(catalogEnv));

apiRouter.use(notFoundHandler());

Configure catalog locations

Add locations to app config so the catalog has entities to load. Open app-config.yaml in the root and add a simple setup

Copy 
catalog:
  locations:
    - type: file
      target: ./catalog-info.yaml
    - type: url
      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all.yaml

You can add more providers later. See the Backstage docs for details on configuration.

Run yarn to install and build

From the repo root run

Copy 
yarn install

Then start your app from the root

Copy 
yarn dev

The catalog index page is at path slash catalog and entity pages are at /catalog/[namespace]/[kind]/[name] when entities exist in your catalog.

Changelog

This changelog is produced from commits made to the Backstage Software Catalog plugin since a month ago. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Features

  • Add support for optional spec.type in catalog allow rules. Restrict ingestion to a kind with a specific type. Example filter API entities to type openapi. See #31103. Merged 1 month ago.

Set up Backstage in minutes with Roadie

Get a demo