Backstage Catalog Graph Plugin

What you get

This plugin is frontend only. There is no backend package to install.

You can use it in two frontend setups

• legacy app system
• new frontend system

Follow the section that matches your app. You can install both safely. The plugin will work in either setup.

Legacy app system

1. Add the dependency to your app

   Copy

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

2. Add the Catalog Graph page route in packages/app/src/App.tsx

   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-dom';
   import { CatalogGraphPage, catalogGraphPlugin } from '@backstage/plugin-catalog-graph';
   import { catalogPlugin } from '@backstage/plugin-catalog';
   
   const app = createApp({
     bindRoutes({ bind }) {
       bind(catalogGraphPlugin.externalRoutes, {
         catalogEntity: catalogPlugin.routes.catalogEntity,
       });
     },
   });
   
   const AppProvider = app.getProvider();
   const AppRouter = app.getRouter();
   
   export const App = () => (
     <AppProvider>
       <AppRouter>
         <FlatRoutes>
           {/* other routes */}
           <Route path="/catalog-graph" element={<CatalogGraphPage />} />
         </FlatRoutes>
       </AppRouter>
     </AppProvider>
   );

   Optional initial filters

   Copy

   <Route
     path="/catalog-graph"
     element={
       <CatalogGraphPage
         initialState={{
           selectedKinds: ['component', 'domain', 'system', 'api', 'group'],
         }}
       />
     }
   />

3. Add the graph card to your entity page so users can see relations on each entity

   Copy

   // packages/app/src/components/catalog/EntityPage.tsx
   import React from 'react';
   import Grid from '@material-ui/core/Grid';
   import { EntityCatalogGraphCard } from '@backstage/plugin-catalog-graph';
   
   export const OverviewContent = () => (
     <Grid container spacing={3}>
       {/* other cards */}
       <Grid item md={6} xs={12}>
         <EntityCatalogGraphCard variant="gridItem" height={400} />
       </Grid>
     </Grid>
   );

   Optional arrow heads for edges

   Copy

   <EntityCatalogGraphCard variant="gridItem" height={400} showArrowHeads />

4. Optional custom relations
   Register the default API with your own relation list in packages/app/src/apis.ts

   Copy

   // packages/app/src/apis.ts
   import { createApiFactory } from '@backstage/core-plugin-api';
   import {
     ALL_RELATIONS,
     ALL_RELATION_PAIRS,
     catalogGraphApiRef,
     DefaultCatalogGraphApi,
   } from '@backstage/plugin-catalog-graph';
   
   export const apis = [
     createApiFactory({
       api: catalogGraphApiRef,
       deps: {},
       factory: () =>
         new DefaultCatalogGraphApi({
           knownRelations: [...ALL_RELATIONS, 'myRelationOf', 'myRelationFor'],
           knownRelationPairs: [
             ...ALL_RELATION_PAIRS,
             ['myRelationOf', 'myRelationFor'],
           ],
           defaultRelationTypes: {
             exclude: ['myRelationOf', 'myRelationFor'],
           },
         }),
     }),
     // other APIs
   ];

5. Optional custom node rendering on the page

   Copy

   // packages/app/src/App.tsx
   import { CatalogGraphPage } from '@backstage/plugin-catalog-graph';
   import { MyCustomRenderNode } from './components/MyCustomRenderNode';
   
   <Route
     path="/catalog-graph"
     element={<CatalogGraphPage renderNode={MyCustomRenderNode} />}
   />

6. Optional custom node rendering on the card

   Copy

   // packages/app/src/components/catalog/EntityPage.tsx
   import { EntityCatalogGraphCard } from '@backstage/plugin-catalog-graph';
   import { MyCustomRenderNode } from '../MyCustomRenderNode';
   
   <EntityCatalogGraphCard
     variant="gridItem"
     height={400}
     renderNode={MyCustomRenderNode}
   />

7. Optional direct use of the lower level component if you need a fully custom view

   Copy

   // any component file
   import React from 'react';
   import { EntityRelationsGraph, Direction } from '@backstage/plugin-catalog-graph';
   
   export const MyGraph = () => (
     <EntityRelationsGraph
       rootEntityNames={{ kind: 'Component', namespace: 'default', name: 'my-service' }}
       maxDepth={2}
       direction={Direction.LEFT_RIGHT}
       mergeRelations
       unidirectional
     />
   );

New frontend system

1. Add the dependency to your app

   Copy

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

2. Enable the entity relations card in app-config.yaml
   The card is not enabled by default

   Copy

   # app-config.yaml
   app:
     packages: all
     extensions:
       - entity-card:catalog-graph/relations

   Optional card config

   Copy

   # app-config.yaml
   app:
     extensions:
       - entity-card:catalog-graph/relations:
           config:
             title: 'Entities Relations Graph'
             height: 400
             maxDepth: 1
             unidirectional: true
             mergeRelations: true
             direction: LR
             zoom: enabled

3. The graph page is enabled by default
   You can change the path

   Copy

   # app-config.yaml
   app:
     extensions:
       - page:catalog-graph:
           config:
             path: '/entity-graph'

   Optional initial filters on the page

   Copy

   # app-config.yaml
   app:
     extensions:
       - page:catalog-graph:
           config:
             initialState:
               selectedKinds: ['component', 'domain', 'system', 'api', 'group']
               maxDepth: 2
               unidirectional: true
               mergeRelations: true
               direction: LR
               curve: curveStepBefore

4. Optional route bindings in config
   Bind the external entity page reference if your app uses a non default entity route
   Or point another plugin route to the catalog graph page

   Copy

   # app-config.yaml
   app:
     routes:
       bindings:
         catalog-graph.catalogEntity: catalog.catalogEntity
         some-plugin.some-external-route: catalog-graph.catalogGraph

5. Optional feature discovery rules per environment

   Copy

   # app-config.production.yaml
   app:
     packages:
       include:
         - '@backstage/plugin-catalog-graph'

   Copy

   # app-config.local.yaml
   app:
     packages:
       exclude:
         - '@backstage/plugin-catalog-graph'

6. Optional direct use of exported components in custom code

   Copy

   // you can still import and render the page or card in custom modules
   import { CatalogGraphPage, EntityCatalogGraphCard } from '@backstage/plugin-catalog-graph';