backstage/plugins/tech-insights/README.md

Tech Insights

This plugin provides the UI for the @backstage/tech-insights-backend plugin, in order to display results of the checks running following the rules and the logic defined in the @backstage/tech-insights-backend plugin itself.

Main areas covered by this plugin currently are:

• Providing an overview for default boolean checks in a form of Scorecards.

• Providing an option to render different custom components based on type of the checks running in the backend.

Installation

Install the plugin

# From your Backstage root directory
yarn add --cwd packages/app @backstage/plugin-tech-insights

Add boolean checks overview (Scorecards) page to the EntityPage:

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

import { EntityTechInsightsScorecardContent } from '@backstage/plugin-tech-insights';

const serviceEntityPage = (
  <EntityLayoutWrapper>
    <EntityLayout.Route path="/" title="Overview">
      {overviewContent}
    </EntityLayout.Route>
    <EntityLayout.Route path="/ci-cd" title="CI/CD">
      {cicdContent}
    </EntityLayout.Route>
    ...
    <EntityLayout.Route path="/tech-insights" title="Scorecards">
      <EntityTechInsightsScorecardContent
        title="Customized title for the scorecard"
        description="Small description about scorecards"
      />
    </EntityLayout.Route>
    ...
  </EntityLayoutWrapper>
);

It is obligatory to pass title prop to EntityTechInsightsScorecardContent, description prop is optional.

If you like to display multiple cards in a EntityLayout.Route use EntityTechInsightsScorecardCard.

You can pass an array checksId as a prop with the Fact Retrievers ids to limit which checks you want to show in this card. If you don't pass, the default value is show all checks.

<EntityTechInsightsScorecardContent
  title="Show only simpleTestCheck in this card"
  checksId={['simpleTestCheck']}
/>

If you want to show checks in the overview of an entity use EntityTechInsightsScorecardCard.

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

import { EntityTechInsightsScorecardCard } from '@backstage/plugin-tech-insights';

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    {entityWarningContent}
    <Grid item md={6} xs={12}>
      <EntityAboutCard variant="gridItem" />
    </Grid>
    <Grid item md={6} xs={12}>
      <EntityCatalogGraphCard variant="gridItem" height={400} />
    </Grid>
    ...
    <Grid item md={8} xs={12}>
      <EntityTechInsightsScorecardCard
        title="Customized title for the scorecard"
        description="Small description about scorecards"
        checksId={['simpleTestCheck']}
      />
    </Grid>
  </Grid>
);

Boolean Scorecard Example

If you follow the Backend Example, once the needed facts have been generated the default boolean scorecard will look like this:

Adding custom rendering components

Default scorecard implementation displays only boolean check results. If you would like to support different types, you need to inject custom rendering components to the TechInsightsClient constructor.

// packages/app/src/apis.ts

export const apis: AnyApiFactory[] = [
...
  createApiFactory({
    api: techInsightsApiRef,
    deps: { discoveryApi: discoveryApiRef, identityApi: identityApiRef },
    factory: ({ discoveryApi, identityApi }) =>
      new TechInsightsClient({
        discoveryApi,
        identityApi,
        renderers: [
          booleanCheckResultRenderer, // default boolean renderer
          myCustomNumberRenderer, // custom renderer
        ],
      }),
  }),
...
];

// packages/app/src/components/myCustomNumberRenderer.tsx

export const myCustomNumberRenderer: CheckResultRenderer = {
  type: 'number',
  component: (checkResult: CheckResult) => (
    <Typography>{checkResult.result}</Typography>
  ),
};