Backstage Relations Plugin

Relations adds custom relationships to your Backstage catalog. It builds on the catalog graph so teams can see how software fits together in their own terms. You define the relation pairs that matter to you. The plugin then shows them in a focused graph with friendlier defaults and filters that include your new relations. It pairs with a processor that emits those relations so the graph reflects your model.

On entity pages you can show a graph card that includes your new relation pairs with arrows enabled by default. You can also add a compact card that lists chosen relations with clear labels. For a broader view there is a full catalog graph page that uses the same filters. This helps with common jobs. Find the real owner of a service. Map supporters for a resource. Follow dependencies across teams. Explore impact before a change. It keeps the catalog useful as it grows.

The project tracks Backstage releases and receives regular updates. It targets recent Backstage versions and stays current with upstream changes. That makes adoption safer in active portals.

Install the frontend package

Run this from your Backstage root.

Copy

yarn --cwd packages/app add @dweber019/backstage-plugin-relations

Use at least Backstage version 1.27.0.

Add the relations graph card to entity pages

Add the relations graph card to your entity pages. It wraps the catalog graph with better defaults. It also adds any custom relation pairs that your backend processor defines.

Copy

// packages/app/src/components/catalog/EntityPage.tsx

import React from 'react';
import { Grid } from '@material-ui/core';
import { EntityLayout } from '@backstage/plugin-catalog';
import { EntityRelationsCatalogGraphCard } from '@dweber019/backstage-plugin-relations';

const groupPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      <Grid container spacing={3}>
        {entityWarningContent}
        {/* other cards */}
        <Grid item md={6} xs={12}>
          <EntityRelationsCatalogGraphCard variant="gridItem" height={400} />
        </Grid>
        {/* other cards */}
      </Grid>
    </EntityLayout.Route>
  </EntityLayout>
);

Add the relations list card to entity pages

Use this card to show a list of specific relations with labels. If you skip the list, only custom relations show.

Copy

// packages/app/src/components/catalog/EntityPage.tsx

import React from 'react';
import { Grid } from '@material-ui/core';
import { EntityLayout } from '@backstage/plugin-catalog';
import { EntityRelationsCard } from '@dweber019/backstage-plugin-relations';

export const relationLabels = [
  { name: 'applicationOwnerOf', label: 'Application owner of' },
  { name: 'applicationOwnerBy', label: 'Application owner' },
];

const userPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      <Grid container spacing={3}>
        {entityWarningContent}
        {/* other cards */}
        <Grid item md={6} xs={12}>
          <EntityRelationsCard relations={relationLabels} />
        </Grid>
      </Grid>
    </EntityLayout.Route>
  </EntityLayout>
);

Replace the root catalog graph page

Swap the root graph page to pick up the same defaults and filters.

Copy

// packages/app/src/App.tsx

import React from 'react';
import { Route } from 'react-router';
import { FlatRoutes } from '@backstage/core-app-api';
import { RelationsCatalogGraphPage } from '@dweber019/backstage-plugin-relations';

const routes = (
  <FlatRoutes>
    {/* other routes */}
    <Route path="/catalog-graph" element={<RelationsCatalogGraphPage />} />
  </FlatRoutes>
);

Install the backend processor package for the legacy backend

This plugin needs the relations processor on the backend. Install it in your backend package.

Copy

yarn --cwd packages/backend add @dweber019/backstage-plugin-relations-backend

Copy

// packages/backend/src/plugins/catalog.ts

import { PluginEnvironment } from '../types';
import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
import { Router } from 'express';
import { RelationsProcessor } from '@dweber019/backstage-plugin-relations-backend';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  const builder = await CatalogBuilder.create(env);

  // Add the relations processor
  builder.addProcessor(new RelationsProcessor());

  const { processingEngine, router } = await builder.build();
  await processingEngine.start();
  return router;
}

Add or adjust any required config for the relations processor in your app config as needed by your setup.

Install the backend processor module for the new backend system

If you use the new backend system, add the module to your backend instance.

Install the same backend package in your backend.

Copy

yarn --cwd packages/backend add @dweber019/backstage-plugin-relations-backend

Copy

// packages/backend/src/index.ts

import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// core plugins
backend.add(import('@backstage/plugin-app-backend').then(m => m.default()));
backend.add(import('@backstage/plugin-catalog-backend').then(m => m.catalogPlugin()));

// add the relations processor module
backend.add(
  import('@dweber019/backstage-plugin-relations-backend').then(m =>
    // the module export name can be catalogModuleRelationsProcessor
    // if your version exports a different name, use that export here
    m.catalogModuleRelationsProcessor(),
  ),
);

backend.start();

If your version exposes a RelationsProcessor class instead of a module, use the module export that the package provides for the new backend system. Keep only one registration.

Add or adjust any required config for the relations processor in your app config.

Summary

You installed the frontend package. You added the graph card and the relations list card to entity pages. You replaced the root catalog graph route. You installed the backend processor. You registered it either in the legacy catalog builder or in the new backend system.

Backstage Relations Plugin

Installation Instructions

Install the frontend package

Add the relations graph card to entity pages

Add the relations list card to entity pages

Replace the root catalog graph page

Install the backend processor package for the legacy backend

Install the backend processor module for the new backend system

Summary

Changelog

Relations

Maintenance

Relations backend

Maintenance

Breaking changes

Set up Backstage in minutes with Roadie