catalog-graph

Welcome to the catalog graph plugin! The catalog graph visualizes the relations between entities, like ownership, grouping or API relationships.

The plugin comes with these features:

• EntityCatalogGraphCard: A card that displays the directly related entities to the current entity. This card is for use on the entity page. The card can be customized, for example filtering for specific relations.

• CatalogGraphPage: A standalone page that can be added to your application providing a viewer for your entities and their relations. The viewer can be used to navigate through the entities and filter for specific relations. You can access it from the EntityCatalogGraphCard.

• EntityRelationsGraph: A react component that can be used to build own customized entity relation graphs.

Installation

# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-catalog-graph
Copy

Once installed, the plugin is automatically available in your app through the default feature discovery. For more details and alternative installation methods, see installing plugins.

To enable the entity relations graph card on the catalog entity page, add the following configuration:

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

For the full list of available extensions and their configuration options, see the README-alpha.md.

Customizing the UI

Copy the default implementation DefaultRenderNode.tsx and add more classes to the styles:

const useStyles = makeStyles(
    theme => ({
        node: {
            …
            '&.system': {
                fill: '#F5DC70',
                stroke: '#F2CE34',
            },
            '&.domain': {
                fill: '#F5DC70',
                stroke: '#F2CE34',
            },
        …
);
Copy

Now you can use the new classes in your component with className={classNames(classes.node, kind?.toLowerCase(), type?.toLowerCase())}

return (
  <g onClick={onClick} className={classNames(onClick && classes.clickable)}>
    <rect
      className={classNames(
        classes.node,
        kind?.toLowerCase(),
        type?.toLowerCase(),
      )}
      width={paddedWidth}
      height={paddedHeight}
    />
    <text
      ref={idRef}
      className={classNames(classes.text, focused && 'focused')}
      y={paddedHeight / 2}
      x={paddedWidth / 2}
      textAnchor="middle"
      alignmentBaseline="middle"
    >
      {displayTitle}
    </text>
  </g>
);
Copy

Once you have your custom implementation, you can follow these steps to modify the required components:

• In the app.tsx update the CatalogGraphPage component to include your custom styles:

<Route path=“/catalog-graph” element={<CatalogGraphPage renderNode={MyCustomRenderNode} />} />
Copy

• In the Entity.tsx file, update the EntityCatalogGraphCard component to this:

<EntityCatalogGraphCard variant=“gridItem” renderNode={MyCustomRenderNode} height={400} />
Copy

Custom relations

Implementers with added custom relations can add them to the catalog graph plugin by overriding the default API. This also allows some relations to not be selected by default.

In packages/app/src/apis.ts, import the api ref and create the API as:

import {
  ALL_RELATIONS,
  ALL_RELATION_PAIRS,
  catalogGraphApiRef,
  DefaultCatalogGraphApi,
} from '@backstage/plugin-catalog-graph';

// ...

  createApiFactory({
    api: catalogGraphApiRef,
    deps: {},
    factory: () =>
      new DefaultCatalogGraphApi({
        // The relations to support
        knownRelations: [...ALL_RELATIONS, 'myRelationOf', 'myRelationFor'],
        // The relation pairs to support
        knownRelationPairs: [
          ...ALL_RELATION_PAIRS,
          ['myRelationOf', 'myRelationFor'],
        ],
        // Select what relations to be shown by default, either by including them,
        // or excluding some from all known relations:
        defaultRelationTypes: {
          // Don't show/select these by default
          exclude: ['myRelationOf', 'myRelationFor'],
        },
      }),
  }),
Copy

Old Frontend System

If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app as outlined in this section. If you are on the new frontend system, you can skip this.

1. Add the CatalogGraphPage to your packages/app/src/App.tsx:

   <FlatRoutes>
     …
     <Route path="/catalog-graph" element={<CatalogGraphPage />} />…
   </FlatRoutes>
   Copy

   You can configure the page to open with some initial filters:

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

2. Bind the external routes of the catalogGraphPlugin in your packages/app/src/App.tsx:

   bindRoutes({ bind }) {
     …
     bind(catalogGraphPlugin.externalRoutes, {
       catalogEntity: catalogPlugin.routes.catalogEntity,
     });
     …
   }
   Copy

3. Add EntityCatalogGraphCard to any entity page that you want in your packages/app/src/components/catalog/EntityPage.tsx:

   <Grid item md={6} xs={12}>
     <EntityCatalogGraphCard variant="gridItem" height={400} />
   </Grid>
   Copy

Development

Run yarn in the root of this plugin to install all dependencies and then yarn start to run a development version of this plugin.