npm

Wie veröffentlicht man eigentlich ein eigenes npm-Package?

Von am 18.02.2021

Es gibt Situationen, in welchen man selbst geschriebene Funktionalität auslagern und wiederverwendbar machen möchte. Dafür eignen sich Paketmanager wie npm hervorragend. Ich selbst habe mich vor einiger Zeit dazu entschlossen, ein solches Paket zu schnüren und möchte in diesem Beitrag Schritt für Schritt erklären, wie dies funktioniert. Ich setze jedoch Grundkenntnisse über die Verwendung von npm als NutzerIn von Paketen anderer voraus, um hier den Fokus auf die wirklich interessanten Aspekte zu lenken.

1. Projekt-Setup

Zunächst – wer hätte es geahnt – benötigt man npm lokal installiert. Um ein neues Paket zu initialisieren navigiert man einfach in der Kommandozeile in den gewünschten Ordner und führt den Befehl npm init aus. Es folgt ein Dialog, dessen Ziel darin besteht, eine package.json-Datei mit einigen Angaben zu erstellen. Möchte man den Dialog überspringen und mit den Standardwerten starten, so kann man stattdessen npm init -y ausführen.

„package.json“ sollte nun einen Paket-Namen, eine Versionsnummer (hier bietet sich „Semantic Versioning“ an), eine kurze Beschreibung sowie ein Haupt-Skript (der Einstiegspunkt für den geschriebenen Code) enthalten. Darüber hinaus kann eine Lizenz, wie beispielsweise MIT für Open-Source-Projekte und der Name des Autors/der Autorin angegeben werden. package.json könnte nun folgendermaßen aussehen:

{
  "name": "mein-tolles-package",
  "version": "1.0.0",
  "description": "Ein wirklich tolles Package",
  "main": "index.js",
  "author": "Manuela Musterfrau",
  "license": "MIT"
}

Es bietet sich an, den Projektordner mit einer README.md-Datei auszustatten. Diese wird dann später, ähnlich wie auf GitHub, als Info-Text in der Vorschau auf npmjs.com herangezogen. Wer außerdem ohnehin Git verwendet, kann noch ein paar weitere Angaben in package.json machen, nämlich wo das Git-Repository gehostet wird und wo etwaige Bugs verfolgt werden.

{
  "name": "mein-tolles-package",
  "version": "1.0.0",
  "description": "Ein wirklich tolles Package",
  "main": "index.js",
  "author": "Manuela Musterfrau",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git@github.com:manuela-musterfrau/mein-tolles-package.git"
  },
  "bugs": {
    "url": "https://github.com/manuela-musterfrau/mein-tolles-package/issues"
  }
}

Nun kann das eigentliche Coden erfolgen. Etwaige Abhängigkeiten von anderen Paketen werden wie gewohnt mit npm install <Paket-Name> <--save | --save-dev> hinzugefügt. Als Haupt-Skript haben wir index.js definiert; es kann aber prinzipiell ein beliebiger Name gewählt werden.

2. Erstveröffentlichung

Um das Package entweder einem geschlossenen Personenkreis oder der Öffentlichkeit zugänglich zu machen, benötigt man zunächst einmal einen Account bei npmjs.com. Es gibt hier verschiedene Pläne mit mehr oder weniger verfügbaren Features. So ist es aktuell mit der kostenlosen Variante nicht möglich, private Pakete hochzuladen. Wer jedoch ein Open-Source-Projekt betreibt, braucht sich darüber keine Gedanken zu machen. In unserem Beispiel begnügen wir uns mit dieser Einschränkung und veröffentlichen unseren Code.

Eine Sache, die es zu beachten gilt, ist die Verfügbarkeit des gewählten Paket-Namen. Dieser darf noch nicht von einem anderen Paket verwendet worden sein. Sollte der Name bereits vergeben sein, so kann man stattdessen im eigenen „Scope“ arbeiten. Jeder User und jede Organisation haben einen eigenen Namespace, welchem einzelne Projekte untergeordnet werden können. Der Paket-Name erhält dann ein Präfix (z. B. @manuela-musterfrau/mein-tolles-package).

Bevor das Paket nun veröffentlicht wird, müssen die Zugangsdaten zum jeweiligen npm-Account eingegeben werden, und zwar nach dem Kommando npm adduser. Nach der erfolgreichen Anmeldung kann nun mit npm publish die Veröffentlichung gestartet werden. Sucht man anschließend auf npmjs.com mittels Eingabefeld nach dem eigenen Paket, sollte es bereits in den Suchergebnissen aufscheinen und zur Installation bereitstehen (siehe Abschnitt 4). Möchte man einzelne Dateien ignorieren, so kann eine Datei .npmignore angelegt werden, welche – ähnlich wie in einer .gitignore-Datei – ein Liste mit zu ignorierenden Dateinamen und Verzeichnissen enthält. Die betreffenden Dateien werden beim Publizieren nicht in das Paket aufgenommen, bleiben aber selbstverständlich lokal und im Git-Repository erhalten.

3. Updates

Um ein Update zu publizieren, sollte zunächst die Versionsnummer erhöht werden. Je nach Update-Typ (major, minor oder patch) lautet der Kommandozeilenbefehl dafür unterschiedlich, folgt aber dem Schema npm version <Update-Typ>. Auch Pre-Release-Nummern werden unterstützt. Man braucht zum Erhöhen dieser Nummer den Befehl npm version prerelease --preid=<alpha|beta|rc>. Die in package.json enthaltene Versionsnummer wird so automatisch angepasst. Mit npm publish kann die neue Version schließlich wieder veröffentlicht werden.

4. Nutzung des Packages

Die Nutzung des Pakets durch andere erfolgt nun genau gleich wie man dies bereits von anderen Projekt-Abhängigkeiten kennt. Durch Ausführen des Befehls npm install mein-tolles-package <--save | --save-dev> erhält man die aktuelle Version. Wird eine bestimmte Version benötigt, so kann die Versionsnummer folgendermaßen an den Namen des Pakets angehängt werden: npm install mein-tolles-package@<Versionsnummer>.

Beitrag kommentieren

(*) Pflichtfeld