Backstage NPM Plugin

Install the frontend plugin in a classic Backstage app

1. Add the package to your app

   Copy

   yarn workspace app add @backstage-community/plugin-npm

2. Import the components in packages/app/src/components/catalog/EntityPage.tsx

   Copy

   // after other imports
   import {
     isNpmAvailable,
     EntityNpmInfoCard,
     EntityNpmReleaseOverviewCard,
     EntityNpmReleaseTableCard,
   } from '@backstage-community/plugin-npm';

3. Show the cards on the entity overview page

   Add this to the overview content after EntityAboutCard

   Copy

   <EntitySwitch>
     <EntitySwitch.Case if={isNpmAvailable}>
       <Grid container item md={6} xs={12}>
         <Grid item md={12}>
           <EntityNpmInfoCard />
         </Grid>
         <Grid item md={12}>
           <EntityNpmReleaseOverviewCard />
         </Grid>
       </Grid>
     </EntitySwitch.Case>
   </EntitySwitch>

4. Add the releases tab to the entity page

   Add this route in serviceEntityPage and websiteEntityPage after the ci cd case
   Add it in defaultEntityPage between the slash route and the docs route

   Copy

   <EntityLayout.Route
     if={isNpmAvailable}
     path="/npm-releases"
     title="NPM Releases"
   >
     <EntityNpmReleaseTableCard />
   </EntityLayout.Route>

Use the new frontend system alpha

1. Add the package to your app next workspace

   Copy

   yarn workspace app-next add @backstage-community/plugin-npm

2. Register the feature in packages/app-next/src/App.tsx or packages/app/src/App.tsx if you run the new system there

   Copy

   import npmPlugin from '@backstage-community/plugin-npm/alpha';
   
   export const app = createApp({
     features: [
       catalogPlugin,
       catalogImportPlugin,
       userSettingsPlugin,
       npmPlugin,
       // other features
     ],
   });

Install the backend plugin new backend system

Required for private packages or for custom registries

1. Add the backend package

   Copy

   yarn workspace backend add @backstage-community/plugin-npm-backend

2. Register it in packages/backend/src/index.ts

   Copy

   // inside your backend setup
   backend.add(import('@backstage-community/plugin-npm-backend'));

3. Optional force the frontend to use the backend for all entities

   Copy

   # app-config.yaml
   npm:
     defaultRegistry: npmjs

Old backend system support

This plugin exposes a new backend system feature. The old backend system is not supported.
For public packages you can run the frontend part only

Configure registries

Default public registry works without extra config for public packages

# app-config.yaml
npm:
  registries:
    - name: npmjs
      url: https://registry.npmjs.com

Private npmjs with token

# app-config.yaml
npm:
  registries:
    - name: npmjs
      url: https://registry.npmjs.com
      token: YOUR_TOKEN

Custom registry

# app-config.yaml
npm:
  registries:
    - name: private-registry
      url: https://your.registry.example.com
      token: YOUR_TOKEN

GitHub registry

# app-config.yaml
npm:
  registries:
    - name: github
      url: https://npm.pkg.github.com
      token: ghp_your_token

To make the backend handle requests for an entity set a matching registry on the entity

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: a-component
  annotations:
    npm/package: private-package
    npm/registry: npmjs

Add entity annotations

Basic setup

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: react
  annotations:
    npm/package: react

Pick a tag other than latest for the info card

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: react
  annotations:
    npm/package: react
    npm/stable-tag: next

Use a named custom registry from your config

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: react
  annotations:
    npm/package: another-package
    npm/registry: github

Optional sample entities

You can import ready made examples for testing

# catalog-info.yaml
catalog:
  locations:
    - type: url
      target: https://github.com/backstage/community-plugins/blob/main/workspaces/npm/examples/entities.yaml
      rules:
        - allow: [System, Component]