Privates NPM Repository mit Verdaccio (SSL, Docker) – Teil 3: Handhabung Verdaccio & npm

Als Angular Entwickler stellt man schnell fest, dass sich viele Components / Modules / Directives / Services & Co. in mehreren Projekten wiederverwenden lassen. Da bietet sich natürlich ein eigenes privates Repository zum Hosten und Bereitstellen von NPM Packages an.

Bei Zotorn IT haben wir uns derzeit für die open source Lösung Verdaccio (https://verdaccio.org/, https://github.com/verdaccio/verdaccio) entschieden. Verdaccio kann man kinderleicht aufsetzen und konfigurieren.

Der Artikel besteht insgesamt aus 4 Teilen:

Teil 3: Handhabung Verdaccio & npm

Verdaccio läuft und jetzt?

Zuerst benötigen wir ein npm-Package, welches wir in unser Repository hochladen können. Wir erstellen schnell ein einfaches Angular Library Package für unsere Testzwecke:

# Für eine Angular Library benötigen erstmal einen Workspace
ng new test-lib-workspace --create-application=false

# Anschließend die Library selbst erstellen
cd test-lib-workspace
ng g library test-lib

Natürlich kannst du auch einen scoped Package Namen mit @ verwenden. Bei Zotorn IT verwenden wir immer @zit/package-name. Ich habe übrigens auch einen Artikel über die Erstellung von Angular Libraries geschrieben, welcher in Kürze erscheint.

Verdaccio erlaubt in seiner Default-Config (config.yaml) nur autorisierten Benutzen das Veröffentlichen (Publishing) von Packages. Die Benutzerregistrierung ist aber für jedermann möglich. Keine Sorge, in Teil 4 werden wir das abschalten.

Also registrieren wir uns erstmal:

# Username, Passwort und E-Mail sind anzugeben
npm adduser --registry=http://localhost:4873/

Output:
Username: tom
Password: 
Email: (this IS public) info@zotorn.de
Logged in as tom on http://localhost:4873/.

Der npm adduser Befehl erstellt einen neuen Benutzer, sofern nicht vorhanden, und loggt sich direkt ein.

Mit dem Parameter --registry geben wir die URL unserer Verdaccio Registry an. Wenn wir den Parameter weglassen, wird als Default die https://registry.npmjs.org/ Registry gewählt. Dort können wir natürlich auch Packages veröffentlichen und für private Packages fallen monatliche Kosten an.

Der Hinweis Email: (this IS public) bezieht sich vermutlich eher auf die npmjs-Registry, weil bei Verdaccio wäre mir das bis jetzt nicht aufgefallen.

Jetzt können wir unser erstes Package veröffentlichen:

# Package bauen
ng build test-lib --prod

# Package veröffentlichen vom frisch gebauten dist/test-lib Verzeichnis
cd dist/test-lib
npm publish --registry=http://localhost:4873 

Output:
.....
npm notice shasum:        e6d706db43c0598bac84d6e049b6ab3e01641aa5
npm notice integrity:     sha512-REAtS/ccyYBIL[...]b3tIz7trTq8eg==
npm notice total files:   15                                      
npm notice 
+ test-lib@0.0.1

Wir prüfen auf dem Webserver, den du über http://localhost:4873/ aufrufen kannst, ob das Package vorhanden ist.

Damit der eigene Name statt Anonymous angezeigt wird, muss man die package.json im library Projekt anpassen.

# /projects/test-lib/package.json
{
  "name": "test-lib",
  "version": "0.0.1",
  "peerDependencies": {
    "@angular/common": "^9.0.1",
    "@angular/core": "^9.0.1",
    "tslib": "^1.10.0"
  },
  "author": {
    "name": "Tom",
    "email": "info@zotorn.de"
  }
}

Die Registry meckert jetzt, wenn wir npm publish nochmal ausführen. So wird verhindert, dass wir die veröffentlichte Version einfach ändern. In einem öffentlichen Repository ergibt dieser Schutzmechanismus absolut Sinn, weil sich andere auf die Integrität des Packages verlassen. Wir können also entweder eine neue Version hochladen oder die Veröffentlichung rückgängig machen.

A) Neue Version hochladen:

# In /projects/test-lib/package.json die Versionsnummer anpassen
{
  "name": "test-lib",
  "version": "0.0.2",
  .....
}

# Nicht vergessen, erstmal wieder ins Workspace-Verzeichnis wechseln
cd ../..
ng build test-lib --prod
cd dist/test-lib
npm publish --registry=http://localhost:4873

B) Existierende Version überschreiben – total uncool!

# Veröffentlichen aufheben. Mit --force klären wir, wer hier den Ton angibt.
npm unpublish test-lib --force --registry=http://localhost:4873

# und wieder veröffentlichen, aber das kenn wir ja jetzt schon. (Wer hat hier Shell-Script gerufen?)
cd ../..
ng build test-lib --prod
cd dist/test-lib
npm publish --registry=http://localhost:4873

Die Verwendung unserer Libray in einem unserer Projekte läuft dann wie gewohnt mit npm install ab:

npm install test-lib -s --registry=http://localhost:4873

Tipp: Komplettes Package löschen/unpublishen:

Da man die Veröffentlichung von Packages immer nur pro Version rückgängig machen, kann habe ich ein praktisches Helfer Shell Script geschrieben, welches ein komplettes Package entfernt. Das Script liest alle verhandenen Versionen aus und löscht diese anschließend einzeln.

#!/bin/bash

# Variablen anpassen:
PACKAGE=@zit/angular-commons
REGISTRY=https://registry9.de:4873

# Alle vorhandenen Version auslesen
RESULT=$(npm view $PACKAGE versions --registry=$REGISTRY --json --loglevel=silent)

# Im Falle eines Fehler brechen wir hier ab
ERR=$(jq -c '.error?' <<< $RESULT)

if [[ $ERR != "" ]]; then
  echo $RESULT
  exit 0
fi

# Kein Fehler, dann parsen wir das Ergebnis mit `jq` in ein Array mit allen Versionen
VERSION_ARR=$(jq -c -r '.[]' <<< $RESULT);

# Jede Version einzeln löschen
for version in $VERSION_ARR; do
    npm unpublish --force --registry=$REGISTRY $PACKAGE@$version
done

weiter zu Teil 4 – Verdaccio absichern.