feat(npm): add backend to fetch data from private registries

Signed-off-by: Christoph Jerolimov <jerolimov+git@redhat.com>

workspaces/npm/README.md

@@ -1,16 +1,117 @@
-# [Backstage](https://backstage.io)
+# npm plugin for Backstage
 
-This is your newly scaffolded Backstage App, Good Luck!
+A Backstage plugin that shows information and latest releases/versions from a npm registry
+for catalog entities.
 
-To start the app, run:
+## Screenshots
 
-```sh
-yarn install
-yarn dev
+### Npm info card
+
+![Screenshot](docs/npm-info-card.png)
+
+### Npm release overview card
+
+![Screenshot](docs/npm-release-overview-card.png)
+
+### Extended catalog entity overview tab (example)
+
+![Screenshot](docs/catalog-entity-overview-tab.png)
+
+### New catalog entity npm release tab
+
+![Screenshot](docs/catalog-entity-npm-release-tab.png)
+
+## For users
+
+### Enable npm cards for a catalog entity
+
+To enable the different npm cards you must add the `npm/package` annotation
+with the name of the npm package:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: react
+  annotations:
+    npm/package: react
+```
+
+The "npm info" card shows the information of the latest 'stable' npm release
+and use the common `latest` tag by default. This could be changed with `npm/stable-tag`:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: react
+  annotations:
+    npm/package: react
+    npm/stable-tag: latest, stable, next, etc.
 ```
 
-To generate knip reports for this app, run:
+## For administrators
+
+### Install on Backstage
+
+1. Install the frontend plugin:
+
+   ```sh
+   yarn workspace app add @backstage-community/plugin-npm
+   ```
+
+2. Add cards based on your needs to `packages/app/src/components/catalog/EntityPage.tsx`:
+
+   After all other imports:
+
+   ```tsx
+   import {
+     isNpmAvailable,
+     EntityNpmInfoCard,
+     EntityNpmReleaseOverviewCard,
+     EntityNpmReleaseTableCard,
+   } from '@backstage-community/plugin-npm';
+   ```
+
+3. Add to `const overviewContent` after `EntityAboutCard`:
+
+   ```tsx
+   <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 to `const serviceEntityPage` and `const websiteEntityPage` after the `/ci-cd` case
+   and to `const defaultEntityPage` between the `/` and `/docs` routecase.
+
+   ```tsx
+   <EntityLayout.Route
+     if={isNpmAvailable}
+     path="/npm-releases"
+     title="NPM Releases"
+   >
+     <EntityNpmReleaseTableCard />
+   </EntityLayout.Route>
+   ```
+
+### Test catalog entities
+
+For testing purpose you can import this catalog entities:
 
-```sh
-yarn backstage-repo-tools knip-reports
+```yaml
+catalog:
+  locations:
+    - type: url
+      target: https://github.com/backstage/community-plugins/blob/main/workspaces/npm/examples/entities.yaml
+      rules:
+        - allow: [System, Component]
 ```

workspaces/npm/app-config.yaml

@@ -78,21 +78,26 @@ catalog:
   rules:
     - allow: [Component, System, API, Resource, Location]
   locations:
-    # Local example data, file locations are relative to the backend process, typically `packages/backend`
+    # Plugin itself for techdocs
     - type: file
-      target: ../../examples/entities.yaml
-
-    # Local example template
+      target: ../../catalog-info.yaml
     - type: file
-      target: ../../examples/template/template.yaml
-      rules:
-        - allow: [Template]
-
-    # Local example organizational data
+      target: ../../plugins/npm/catalog-info.yaml
+    - type: file
+      target: ../../plugins/npm-backend/catalog-info.yaml
     - type: file
-      target: ../../examples/org.yaml
+      target: ../../plugins/npm-common/catalog-info.yaml
+    # Local example data
+    - type: file
+      target: ../../examples/example-org.yaml
       rules:
         - allow: [User, Group]
+    - type: file
+      target: ../../examples/example-system.yaml
+    - type: file
+      target: ../../examples/npmjs-components.yaml
+    - type: file
+      target: ../../examples/github-components.yaml
 
     ## Uncomment these lines to add more example data
     # - type: url

workspaces/npm/catalog-info.yaml

@@ -2,9 +2,15 @@ apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:
   name: backstage-plugin-npm-workspace
-  title: 'Backstage Community Npm Plugin'
+  title: Backstage Community Npm Plugin
   description: A Backstage plugin that shows meta info and latest versions from a npm registry
+  annotations:
+    backstage.io/techdocs-ref: dir:.
+  links:
+    - url: https://github.com/backstage/community-plugins/tree/main/workspaces/npm
+      title: GitHub
+      icon: sourcecode
 spec:
-  lifecycle: experimental
+  lifecycle: production
   type: backstage-plugin
   owner: maintainers

workspaces/npm/examples/example-system.yaml

@@ -0,0 +1,8 @@
+---
+# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-system
+apiVersion: backstage.io/v1alpha1
+kind: System
+metadata:
+  name: backstage
+spec:
+  owner: guests

workspaces/npm/examples/github-components.yaml

@@ -0,0 +1,14 @@
+---
+# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-component
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: github-packages-examples
+  annotations:
+    npm/registry: github
+    npm/package: '@github-packages-examples/npm-publish'
+spec:
+  type: library
+  lifecycle: production
+  owner: guests
+  system: backstage

workspaces/npm/examples/entities.yaml → workspaces/npm/examples/npmjs-components.yaml

@@ -1,19 +1,12 @@
 ---
-# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-system
-apiVersion: backstage.io/v1alpha1
-kind: System
-metadata:
-  name: backstage
-spec:
-  owner: guests
----
 # https://backstage.io/docs/features/software-catalog/descriptor-format#kind-component
 apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:
   name: backstage-catalog-model
   annotations:
     npm/package: '@backstage/catalog-model'
+    npm/show-tags: latest, next
 spec:
   type: library
   lifecycle: production
@@ -27,6 +20,7 @@ metadata:
   name: backstage-catalog-client
   annotations:
     npm/package: '@backstage/catalog-client'
+    npm/show-tags: latest, next
 spec:
   type: library
   lifecycle: production
@@ -42,6 +36,7 @@ metadata:
   name: backstage-plugin-catalog-common
   annotations:
     npm/package: '@backstage/plugin-catalog-common'
+    npm/show-tags: latest, next
 spec:
   type: library
   lifecycle: production
@@ -57,6 +52,7 @@ metadata:
   name: backstage-plugin-catalog-node
   annotations:
     npm/package: '@backstage/plugin-catalog-node'
+    npm/show-tags: latest, next
 spec:
   type: library
   lifecycle: production
@@ -72,6 +68,7 @@ metadata:
   name: backstage-plugin-catalog-react
   annotations:
     npm/package: '@backstage/plugin-catalog-react'
+    npm/show-tags: latest, next
 spec:
   type: library
   lifecycle: production
@@ -89,6 +86,7 @@ metadata:
   name: backstage-plugin-catalog
   annotations:
     npm/package: '@backstage/plugin-catalog'
+    npm/show-tags: latest, next
 spec:
   type: website
   lifecycle: production

workspaces/npm/mkdocs.yaml

@@ -0,0 +1,8 @@
+site_name: Backstage Community Npm Plugin
+site_description: A Backstage plugin that shows meta info and latest versions from a npm registry
+
+plugins:
+  - techdocs-core
+
+nav:
+  - Customization: index.md

workspaces/npm/packages/app/e2e-tests/app.test.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 The Backstage Authors
+ * Copyright 2024 The Backstage Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

workspaces/npm/packages/backend/package.json

@@ -21,6 +21,7 @@
     "build-image": "docker build ../.. -f Dockerfile --tag backstage"
   },
   "dependencies": {
+    "@backstage-community/plugin-npm-backend": "workspace:^",
     "@backstage/backend-defaults": "^0.5.2",
     "@backstage/config": "^1.2.0",
     "@backstage/plugin-app-backend": "^0.3.76",

workspaces/npm/packages/backend/src/index.ts

@@ -56,4 +56,5 @@ backend.add(import('@backstage/plugin-search-backend-module-pg/alpha'));
 backend.add(import('@backstage/plugin-search-backend-module-catalog/alpha'));
 backend.add(import('@backstage/plugin-search-backend-module-techdocs/alpha'));
 
+backend.add(import('@backstage-community/plugin-npm-backend'));
 backend.start();

workspaces/npm/plugins/npm-backend/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

workspaces/npm/plugins/npm-backend/README.md

@@ -0,0 +1 @@
+../../README.md