Skip to content

Commit 2816eb6

Browse files
christoph-jerolimovchristoph-jerolimov
authored
feat(npm): add backend to fetch data from private registries (#1812)
* feat(npm): add backend to fetch data from private registries Signed-off-by: Christoph Jerolimov <jerolimov+git@redhat.com> * feat(npm): added examples and some small fixes when npm package info is loaded from GitLab Signed-off-by: Christoph Jerolimov <jerolimov+git@redhat.com> --------- Signed-off-by: Christoph Jerolimov <jerolimov+git@redhat.com>
1 parent 2f069c5 commit 2816eb6

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

73 files changed

+2943
-500
lines changed

‎workspaces/npm/.changeset/polite-houses-flow.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@backstage-community/plugin-npm-backend': minor
3+
'@backstage-community/plugin-npm-common': minor
4+
'@backstage-community/plugin-npm': minor
5+
---
6+
7+
Added support for custom and private npm registries like GitHub and GitLab via a new backend plugin. Other npm registries that works with the npm cli should work as well.

‎workspaces/npm/README.md‎

Lines changed: 317 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,324 @@
1-
# [Backstage](https://backstage.io)
1+
# npm plugin for Backstage
22

3-
This is your newly scaffolded Backstage App, Good Luck!
3+
A Backstage plugin that shows information and latest releases/versions
4+
from a npm registry for catalog entities.
45

5-
To start the app, run:
6+
The current version can show two cards and one additional tab for an catalog entity.
67

7-
```sh
8-
yarn install
9-
yarn dev
8+
1. The "Npm info card" shows general information like the latest version, description, etc.
9+
2. The "Npm release overview card" shows the latest tags of an npm package.
10+
3. The "Npm release tab" shows the version hisory in detail.
11+
12+
## Screenshots
13+
14+
### Npm info card
15+
16+
![Screenshot](docs/npm-info-card.png)
17+
18+
### Npm release overview card
19+
20+
![Screenshot](docs/npm-release-overview-card.png)
21+
22+
### Extended catalog entity overview tab (example)
23+
24+
![Screenshot](docs/catalog-entity-overview-tab.png)
25+
26+
### New catalog entity npm release tab
27+
28+
![Screenshot](docs/catalog-entity-npm-release-tab.png)
29+
30+
## Usage
31+
32+
### Enable npm cards for a catalog entity
33+
34+
To enable the different npm cards you must add the `npm/package` annotation
35+
with the name of the npm package:
36+
37+
```yaml
38+
apiVersion: backstage.io/v1alpha1
39+
kind: Component
40+
metadata:
41+
name: react
42+
annotations:
43+
npm/package: react
44+
```
45+
46+
### Use other npm tag then `latest`
47+
48+
The "npm info" card shows the information of the latest 'stable' npm release
49+
and use the common `latest` tag by default. This could be changed with `npm/stable-tag`:
50+
51+
```yaml
52+
# catalog-info.yaml
53+
apiVersion: backstage.io/v1alpha1
54+
kind: Component
55+
metadata:
56+
name: react
57+
annotations:
58+
npm/package: react
59+
npm/stable-tag: latest, stable, next, etc.
1060
```
1161

12-
To generate knip reports for this app, run:
62+
### Use a custom registry
63+
64+
To use another npm registry you need to specific a registry name in your
65+
catalog entity that exists in your `app-config.yaml`.
1366

14-
```sh
15-
yarn backstage-repo-tools knip-reports
67+
```yaml
68+
# catalog-info.yaml
69+
apiVersion: backstage.io/v1alpha1
70+
kind: Component
71+
metadata:
72+
name: react
73+
annotations:
74+
npm/package: another-package
75+
npm/registry: github
1676
```
77+
78+
```yaml
79+
# app-config.yaml
80+
npm:
81+
registries:
82+
- name: github
83+
url: https://npm.pkg.github.com
84+
token: ghp_...
85+
```
86+
87+
## Installation
88+
89+
To show information from a private package or an alternative npm registry
90+
you must install also the backend plugin and [configure it](./registries.md).
91+
92+
### Frontend plugin
93+
94+
1. Install the frontend dependency:
95+
96+
```sh
97+
yarn workspace app add @backstage-community/plugin-npm
98+
```
99+
100+
2. Add cards based on your needs to `packages/app/src/components/catalog/EntityPage.tsx`:
101+
102+
After all other imports:
103+
104+
```tsx
105+
import {
106+
isNpmAvailable,
107+
EntityNpmInfoCard,
108+
EntityNpmReleaseOverviewCard,
109+
EntityNpmReleaseTableCard,
110+
} from '@backstage-community/plugin-npm';
111+
```
112+
113+
3. Add to `const overviewContent` after `EntityAboutCard`:
114+
115+
```tsx
116+
<EntitySwitch>
117+
<EntitySwitch.Case if={isNpmAvailable}>
118+
<Grid container item md={6} xs={12}>
119+
<Grid item md={12}>
120+
<EntityNpmInfoCard />
121+
</Grid>
122+
<Grid item md={12}>
123+
<EntityNpmReleaseOverviewCard />
124+
</Grid>
125+
</Grid>
126+
</EntitySwitch.Case>
127+
</EntitySwitch>
128+
```
129+
130+
4. Add to `const serviceEntityPage` and `const websiteEntityPage` after the `/ci-cd` case
131+
and to `const defaultEntityPage` between the `/` and `/docs` routecase.
132+
133+
```tsx
134+
<EntityLayout.Route
135+
if={isNpmAvailable}
136+
path="/npm-releases"
137+
title="NPM Releases"
138+
>
139+
<EntityNpmReleaseTableCard />
140+
</EntityLayout.Route>
141+
```
142+
143+
### Alternative: Use the new frontend system (alpha)
144+
145+
For early adaopters of the new frontend system.
146+
147+
Your Backstage frontend app must use that new frontend system which isn't the default at the moment.
148+
149+
1. Install the frontend dependency:
150+
151+
```sh
152+
yarn workspace app-next add @backstage-community/plugin-npm
153+
```
154+
155+
2. Add the package to your `packages/app[-next]/src/App.tsx`.
156+
157+
```tsx
158+
import npmPlugin from '@backstage-community/plugin-npm/alpha';
159+
```
160+
161+
And extend your createApp:
162+
163+
```tsx
164+
export const app = createApp({
165+
features: [
166+
catalogPlugin,
167+
catalogImportPlugin,
168+
userSettingsPlugin,
169+
npmPlugin,
170+
// ...
171+
],
172+
});
173+
```
174+
175+
### Optional: Backend plugin (req. for private packages or alternative registries)
176+
177+
1. Install the backend plugin:
178+
179+
```sh
180+
yarn workspace backend add @backstage-community/plugin-npm
181+
```
182+
183+
2. Add it to `packages/backend/src/index.ts`:
184+
185+
```tsx
186+
backend.add(import('@backstage-community/plugin-npm-backend'));
187+
```
188+
189+
3. The backend is only used for catalog entities with a registry by default.
190+
191+
If no `npm/registry` annotation is defined, the npm plugin loads the
192+
information directly from the frontend.
193+
(The browser of the user will connect to https://registry.npmjs.com.)
194+
195+
You can enforce using the backend by defining a default registry:
196+
197+
```yaml
198+
# app-config.yaml
199+
# optional to enforce the frontend to use the backend
200+
npm:
201+
defaultRegistry: npmjs
202+
```
203+
204+
For more information, please checkout the [Registries](./registries.md) documentation.
205+
206+
### Optional: Test with plugin-example catalog entities
207+
208+
For testing purpose you can import this catalog entities:
209+
210+
```yaml
211+
# catalog-info.yaml
212+
catalog:
213+
locations:
214+
- type: url
215+
target: https://github.com/backstage/community-plugins/blob/main/workspaces/npm/examples/entities.yaml
216+
rules:
217+
- allow: [System, Component]
218+
```
219+
220+
## Registries
221+
222+
The npm plugin supports custom and private registries starting with v1.2.
223+
224+
### Default Configuration
225+
226+
The plugin loads information by default from https://registry.npmjs.com
227+
228+
This works without any additional configuration in your `app-config.yaml`
229+
but only for public npm packages.
230+
231+
```yaml
232+
npm:
233+
registries:
234+
- name: npmjs
235+
url: https://registry.npmjs.com
236+
```
237+
238+
### Use an auth token for npmjs
239+
240+
To load information from another registry or to load information
241+
from a private package, you must [install the backend](./install.md).
242+
243+
The catalog entity `npm/registry` annotation must be defined and match
244+
one of the registries in the `app-config.yaml`:
245+
246+
Example:
247+
248+
```yaml
249+
# catalog-info.yaml
250+
apiVersion: backstage.io/v1alpha1
251+
kind: Component
252+
metadata:
253+
name: a-component
254+
annotations:
255+
npm/package: private-package
256+
npm/registry: npmjs
257+
```
258+
259+
```yaml
260+
# app-config.yaml
261+
npm:
262+
registries:
263+
- name: npmjs
264+
url: https://registry.npmjs.com
265+
token: ...
266+
```
267+
268+
The `npm/registry: npmjs` annotation is required to use the npm backend.
269+
270+
Alternativly you can setup a default registry (also for npmjs):
271+
272+
```yaml
273+
# app-config.yaml
274+
npm:
275+
defaultRegistry: npmjs
276+
```
277+
278+
### Use an alternative registry
279+
280+
Entity example:
281+
282+
```yaml
283+
# catalog-info.yaml
284+
apiVersion: backstage.io/v1alpha1
285+
kind: Component
286+
metadata:
287+
name: a-component
288+
annotations:
289+
npm/package: private-package
290+
npm/registry: private-registry
291+
```
292+
293+
```yaml
294+
# app-config.yaml
295+
npm:
296+
registries:
297+
- name: private-registry
298+
url: https://...
299+
token: ...
300+
```
301+
302+
### Use GitHub npm registry
303+
304+
The GitHub npm registry reqires also a GitHub token for public entries.
305+
306+
You need to create a token at https://github.com/settings/tokens
307+
308+
```yaml
309+
# app-config.yaml
310+
npm:
311+
registries:
312+
- name: github
313+
url: https://npm.pkg.github.com
314+
token: ghp_...
315+
```
316+
317+
### Other npm registries
318+
319+
Other npm registries should work the same way.
320+
321+
Please let us know if we should mention here another registry or
322+
if you find any issue.
323+
324+
You can create a new [Issues on GitHub](https://github.com/backstage/community-plugins/issues/new?assignees=&labels=bug&projects=&template=1-bug.yaml&title=🐛+Npm%3A+<Title>)

0 commit comments

Comments
 (0)