Backstage Linguist Plugin

Add the entity annotation

Add this annotation to each entity you want to analyze. Use a source URL that your Backstage UrlReader can read.

# Example catalog-info.yaml entity definition file
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  annotations:
    backstage.io/linguist: https://github.com/backstage/backstage
spec:
  type: service

Linguist uses the UrlReader to fetch files then scans them to find language usage. It works with common providers like GitHub, GitLab, Bitbucket, Azure, Google GCS, and AWS S3.

Install the frontend plugin for the classic frontend

1. Add the package to your app.

   Copy

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

2. Show the card on the entity page.

   Edit packages/app/src/components/catalog/EntityPage.tsx. Import the card and the helper. Add the card to the overview section.

   Copy

   // packages/app/src/components/catalog/EntityPage.tsx
   import React from 'react';
   import Grid from '@material-ui/core/Grid';
   import { EntitySwitch } from '@backstage/plugin-catalog';
   import { isLinguistAvailable, EntityLinguistCard } from '@backstage-community/plugin-linguist';
   
   // inside your overview content
   const overviewContent = (
     <Grid container spacing={3} alignItems="stretch">
       {/* other cards */}
       <EntitySwitch>
         <EntitySwitch.Case if={isLinguistAvailable}>
           <Grid item md={6}>
             <EntityLinguistCard />
           </Grid>
         </EntitySwitch.Case>
       </EntitySwitch>
       {/* other cards */}
     </Grid>
   );

Notes

• You can remove the if prop if you want the card to always render.

Install the frontend plugin for the new frontend system

1. Add the package to your app.

   Copy

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

2. Enable the plugin feature in packages/app or packages/app-next.

   Copy

   // packages/app/src/App.tsx or packages/app-next/src/App.tsx
   import { createApp } from '@backstage/frontend-app-api';
   import catalogPlugin from '@backstage/plugin-catalog/alpha';
   import catalogImportPlugin from '@backstage/plugin-catalog-import/alpha';
   import userSettingsPlugin from '@backstage/plugin-user-settings/alpha';
   
   import linguistPlugin from '@backstage-community/plugin-linguist';
   
   export const app = createApp({
     features: [
       catalogPlugin,
       catalogImportPlugin,
       userSettingsPlugin,
       linguistPlugin,
     ],
   });

Or turn on feature discovery in app-config.yaml.

app:
  packages: all

Install the backend plugin for the classic backend

1. Add the backend package to your backend.

   Copy

   # From your Backstage root directory
   yarn --cwd packages/backend add @backstage-community/plugin-linguist-backend

2. Create the backend plugin wiring.

   Create a new file packages/backend/src/plugins/linguist.ts.

   Copy

   // packages/backend/src/plugins/linguist.ts
   import { Router } from 'express';
   import { PluginEnvironment } from '../types';
   import { createRouter } from '@backstage-community/plugin-linguist-backend';
   
   export default async function createPlugin(
     env: PluginEnvironment,
   ): Promise<Router> {
     return await createRouter({
       logger: env.logger,
       config: env.config,
       reader: env.reader,
       discovery: env.discovery,
       cache: env.cache,
     });
   }

3. Mount the router in the backend.

   Edit packages/backend/src/index.ts. Create the plugin environment then mount the router under the api path.

   Copy

   // packages/backend/src/index.ts
   import { createServiceBuilder } from '@backstage/backend-common';
   import express from 'express';
   import http from 'http';
   import { useHotCleanup } from '@backstage/backend-common';
   import { createEnv } from './lib/createEnv';
   import linguist from './plugins/linguist';
   
   async function main() {
     const apiRouter = express.Router();
   
     const linguistEnv = useHotCleanup(module, () => createEnv('linguist'));
     apiRouter.use('/linguist', await linguist(linguistEnv));
   
     const service = createServiceBuilder(module)
       .setPort(Number(process.env.PORT) || 7007)
       .addRouter('/api', apiRouter);
   
     await service.start().catch(err => {
       process.exit(1);
     });
   }
   
   main().catch(err => {
     process.exit(1);
   });

This exposes the plugin at the api linguist path. The frontend card will call it through the Backstage proxy.

Install the backend plugin for the new backend system

1. Add the backend package to your backend.

   Copy

   # From your Backstage root directory
   yarn --cwd packages/backend add @backstage-community/plugin-linguist-backend

2. Register the module in packages/backend src index.ts.

   Copy

   // packages/backend/src/index.ts
   import { createBackend } from '@backstage/backend-defaults';
   import { catalogModule } from '@backstage/plugin-catalog-backend/alpha';
   import { scaffolderModule } from '@backstage/plugin-scaffolder-backend/alpha';
   
   // The linguist backend module export name may differ depending on version
   // If this import fails, open the package in node_modules and use the exported module function
   import { linguistModule } from '@backstage-community/plugin-linguist-backend';
   
   const backend = createBackend();
   
   backend.add(catalogModule());
   backend.add(scaffolderModule());
   
   backend.add(linguistModule());
   
   backend.start();

If the package exports a default module function, use this instead.

import linguistModule from '@backstage-community/plugin-linguist-backend';

backend.add(linguistModule());

Summary of what you should see in your app

• Entities that have the backstage.io linguist annotation will show the Linguist card on the overview page
• The card will be empty until the backend has scanned the source for that entity
• After the scan the card will show the language breakdown