Best Practices für die Entwicklung eines modernen npm-Pakets mit Blick auf die Sicherheit

Technologien entwickeln sich ständig weiter – Ihre Prozesse und Vorgehensweisen müssen mit diesen Veränderungen Schritt halten. npm ist zwar (Stand 2025) bereits 15 Jahre alt, doch Ihre Vorgehensweisen bei der Erstellung von npm-Paketen sollten hoffentlich deutlich moderner sein. Falls Sie den Eindruck haben, dass sie etwas veraltet sein könnten, lesen Sie weiter. 

In diesem Tutorial zeigen wir Schritt für Schritt, wie Sie nach modernen Best Practices (Stand 2025) ein npm-Paket erstellen. Zunächst erfahren Sie, wie Sie ein npm-Paket erstellen, und machen sich mit dem Erstellen und Veröffentlichen eines Pakets in der npm-Registry vertraut. Anschließend lernen Sie, wie Sie ein robusteres, produktionsreifes npm-Paket entwickeln – mit einem Test-Framework, einer CI/CD-Pipeline, Sicherheitsprüfungen und automatisierter semantischer Versionsverwaltung für Releases. Am Ende dieses Tutorials können Sie moderne, nachhaltige npm-Pakete mit Zuversicht erstellen. Los geht’s!

Voraussetzungen

1. Vertrautheit mit Node.js, JavaScript/TypeScript, GitHub und GitHub Actions

2. Verfügbare Entwicklungstools, die Sie beim Erstellen eines npm-Pakets unterstützen

Ein einfaches npm-Paket als Beispiel

Machen wir uns zunächst anhand eines einfachen Beispiels mit dem Erstellen und Veröffentlichen eines npm-Pakets vertraut. Wenn Sie damit bereits vertraut sind, können Sie direkt zum Abschnitt Produktionsreifes npm-Paket springen, in dem fortgeschrittenere Themen behandelt werden.

Richten Sie Ihr Projekt ein

Für den Einstieg benötigen Sie ein GitHub-Projekt. Folgen Sie diesen Schritten, um ein Projekt anzulegen. Wenn Sie bereits ein Projekt verwenden können, überspringen Sie diesen Abschnitt. Achten Sie aber darauf, Schritt 5 in diesem Abschnitt zum Paketnamen noch einmal genau zu prüfen.

• Erstellen Sie ein GitHub-Repository: https://github.com/new

• Klonen Sie das Repository auf Ihren lokalen Rechner.
  Beispiel: git clone https://github.com/snyk-snippets/simple-npm-package.git

• Öffnen Sie Ihr Terminal und wechseln Sie in den Ordner des geklonten Projekts.
  Beispiel: cd simple-npm-package

• Führen Sie npm init -y aus, um eine Datei package.json zu erstellen. Hinweis: Wenn Sie das Beispiel-Repository geklont haben, müssen Sie diesen Schritt nicht ausführen.

• Aktualisieren Sie die Eigenschaft name in package.json mit einem Namen mit Scope.
  Beispiel: @clarkio/simple-npm-package. Verwenden Sie anstelle von @clarkio Ihren Benutzernamen oder den Namen Ihrer Organisation.

• Schreiben Sie den Code für Ihr Paket (oder verwenden Sie einfach das „Hello World“-Beispiel in index.js).

Sobald Ihr Projekt erstellt ist, können Sie ein npm-Konto einrichten.

Richten Sie ein npm-Konto ein

Damit andere Ihr npm-Paket verwenden können, benötigen Sie ein npm-Konto. Mit den folgenden Schritten erstellen Sie ein eigenes Konto (falls Sie noch keines haben), aktivieren die Zwei-Faktor-Authentifizierung (2FA), um die Sicherheit Ihres Kontos zu erhöhen, und verbinden Ihr Konto mit Ihrem lokalen Rechner.

1. Registrieren Sie sich bei npm unter https://www.npmjs.com/signup. 

2. Aktivieren Sie für mehr Sicherheit 2FA für Ihr npm-Konto: https://docs.npmjs.com/configuring-two-factor-authentication. 

3. Melden Sie sich in Ihrem Terminal mit dem Befehl npm login bei Ihrem npm-Konto an und folgen Sie den Anweisungen auf dem Bildschirm. Zum Beispiel:

1> npm login
2npm notice Log in on https://registry.npmjs.org/
3Username: clarkio
4Password:
5Email: (this IS public) <email address>
6npm notice Please use the one-time password (OTP) from your authenticator application
7Enter one-time password from our authenticator app: <OTP>
8Logged in as clarkio on https://registry.npmjs.org/.

So veröffentlichen Sie Ihr npm-Paket

Sobald Sie ein npm-Projekt und ein npm-Konto haben, können Sie Ihr npm-Paket in der öffentlichen offiziellen npmjs-Registry veröffentlichen, damit andere es verwenden können. Folgen Sie diesen Schritten, um vor der Veröffentlichung zu prüfen, was veröffentlicht wird, und anschließend das Paket tatsächlich zu veröffentlichen:

1. Führen Sie in Ihrem Terminal npx pack --dry-run aus, um zu sehen, welche Inhalte in der veröffentlichten Version des Pakets enthalten sein werden.

1> npx pack --dry-run
2npm notice Tarball Contents
3npm notice 1.1kB LICENSE
4npm notice 1.9kB README.md
5npm notice 108B index.js
6npm notice 700B package.json
7npm notice Tarball Details

So stellen Sie sicher, dass keine für die korrekte Funktionsweise des Pakets erforderlichen Quelldateien fehlen. Außerdem sollten Sie prüfen, dass Sie nicht versehentlich vertrauliche Informationen öffentlich zugänglich machen, etwa eine lokale Konfigurationsdatei mit Datenbank-Anmeldedaten oder API-Schlüsseln.

2. Führen Sie in Ihrem Terminal npm publish --dry-run aus, um zu sehen, was bei der tatsächlichen Ausführung des Befehls passieren würde.

1> npm publish --dry-run
2npm notice
3npm notice 📦@clarkio/simple-npm-package@0.0.1
4npm notice === Tarball Contents ===
5npm notice 1.1kB LICENSE
6npm notice 1.2kB README.md
7npm notice 95B index.js
8npm notice 690B package.json
9npm notice === Tarball Details===
10npm notice name: @clarkio/simple-npm-package
11npm notice version: 0.0.1
12npm notice filename:@clarkio/simple-npm-package-0.0.1.tgz
13npm notice package size:1.7 kB
14npm notice unpacked size: 3.1 kB
15npm notice shasum:40ede3ed630fa8857c0c9b8d4c81664374aa811c
16npm notice integrity:sha512-QZCyWZTspkcUXL... ]L60ZKBOOBRLTg==
17npm notice total files:4
18npm notice
19+ @clarkio/simple-npm-package@0.0.1

3. Führen Sie in Ihrem Terminal npm publish --access=public aus, um das Paket tatsächlich auf npm zu veröffentlichen. Hinweis: Für Pakete mit Scope (@clarkio/modern-npm-package) ist --access=public erforderlich, da sie standardmäßig privat sind. Pakete ohne Scope sind ebenfalls öffentlich, sofern das Feld private in Ihrer package.json nicht auf true gesetzt ist.

1> npm publish --access=public
2npm notice
3npm notice 📦@clarkio/simple-npm-package@0.0.1
4npm notice === Tarball Contents ===
5npm notice 1.1kB LICENSE
6npm notice 1.2kB README.md
7npm notice 95B index.js
8npm notice 690B package.json
9npm notice === Tarball Details===
10npm notice name: @clarkio/simple-npm-package
11npm notice version: 0.0.1
12npm notice filename:@clarkio/simple-npm-package-0.0.1.tgz
13npm notice package size:2.1 kB
14npm notice unpacked size: 4.1 kB
15npm notice shasum:6f335d6254ebb77a5a24ee729650052a69994594
16npm notice integrity:sha512-VZ1K1eMFOKeJW[...]7ZjKFVAxLcpdQ==
17npm notice total files:4
18npm notice
19This operation requires a one-time password.
20Enter OTP: <OTP>
21+ @clarkio/simple-npm-package@0.0.1

Fertig! Sie haben Ihr eigenes npm-Paket erstellt und bereitgestellt. Als Nächstes erfahren Sie, wie Sie ein robusteres Paket entwickeln, das für Produktionsumgebungen geeignet ist und breiter eingesetzt werden kann.

Produktionsreifes npm-Paket

Das zuvor gezeigte Beispielpaket könnte zwar in der Produktion eingesetzt werden, seine laufende Wartung erfordert jedoch manuelle Arbeit. Mit Tools und Automatisierung sowie geeigneten Tests und Sicherheitsprüfungen können Sie den Gesamtaufwand für einen reibungslosen Betrieb des Pakets verringern. Sehen wir uns genauer an, was dazugehört.

In den folgenden Abschnitten geht es um:

1. Einrichten Ihres modern-npm-package-Projekts

2. Erstellen im ECMAScript-Modulformat (ESM)

3. Einrichten und Schreiben von Unit-Tests

4. Implementieren von Sicherheitsprüfungen

5. Automatisieren der Versionsverwaltung und Veröffentlichung

Wenn Sie kein eigenes Projekt haben, das Sie während der Arbeit mit diesem Artikel verwenden können, dient Ihnen das folgende Beispielprojekt als Referenz: https://github.com/snyk-snippets/modern-npm-package.

Erstellen im ECMAScript-Modulformat

Das ECMAScript-Modulformat wird ab Node.js Version 12+ nativ unterstützt. Die aktuelle Long-Term-Support-Version ist 22.x. Auch im Bereich der JavaScript-Runtimes gibt es mit Angeboten wie Bun.js und Deno mehr Wettbewerb – und all diese Entwicklungen machen es einfach, jetzt auf das ESM-Format zu setzen. Wir verwenden TypeScript, um Ihr npm-Paket für das ESM-Format vorzubereiten.

• Erstellen Sie zunächst eine TypeScript-Konfigurationsdatei namens tsconfig.json. Darin werden die Kompilierungseinstellungen festgelegt, die beim Erstellen Ihres Pakets im ESM-Format zum Einsatz kommen. Passen Sie die Einstellungen nach Bedarf an Ihr Projekt an. Insbesondere sollten Sie die Eigenschaft files an Ihre Projektstruktur anpassen, wenn Sie nicht das bereitgestellte Beispiel verwenden.

1{
2    "compilerOptions": {
3      "lib": ["ES2024", "DOM"],
4      "target": "ES2024",
5      "module": "NodeNext",
6      "moduleResolution": "NodeNext",
7      "outDir": "./lib/",
8      "declarationDir": "./lib/types",
9      "strict": true,
10      "esModuleInterop": true,
11      "forceConsistentCasingInFileNames": true,
12      "skipLibCheck": true,
13      "checkJs": true,
14      "allowJs": true,
15      "declaration": true,
16      "declarationMap": true,
17      "allowSyntheticDefaultImports": true
18    },
19    "files": ["./src/index.ts"]
20  }

• Die Eigenschaft lib gibt an, auf welche Typen TypeScript beim Schreiben des Projektcodes zurückgreifen soll.

• Die Eigenschaft target gibt an, in welche JavaScript-Version TypeScript Ihren Projektcode kompilieren soll.

• Die Eigenschaft module gibt an, welches JavaScript-Modulformat TypeScript beim Kompilieren Ihres Projektcodes verwenden soll.

• Die Eigenschaft moduleResolution hilft TypeScript dabei zu bestimmen, wie eine „import“-Anweisung aufgelöst werden soll.

• Die Eigenschaften outDir und declarationDir geben an, wo TypeScript die Ergebnisse der Kompilierung Ihres Codes und die darin verwendeten Typdefinitionen ablegen soll.

2. Aktualisieren Sie Ihre Datei package.json um ein Feld files, das auf Ihren Ordner lib mit den Ergebnissen des Paket-Builds durch TypeScript verweist.

3. Aktualisieren Sie in Ihrer Datei package.json die Felder main und types , sodass sie auf die Ausgabe des erstellten bzw. kompilierten Pakets verweisen. Diese dienen als Standard- und Fallback-Option.

1"types": "./lib/index.d.ts",
2  "main": "./lib/index.js",

4. Fügen Sie Ihrer Datei package.json ein Feld files hinzu, um anzugeben, welche Dateien npm beim Packen Ihres Codes für die Veröffentlichung einschließen soll.

1"files": [
2   "lib/**/*"
3],

5. Erstellen Sie über das Feld scripts in package.json Befehle, die tsc zum Kompilieren des Pakets verwenden. Dadurch werden die Quelldateien für den Ordner lib generiert.

1    "clean": "del-cli ./lib",
2    "build": "npm run clean && tsc -p ./tsconfig.json",
3    "prepack": "npm run build",

• Das Skript clean löscht die Ausgaben früherer Builds, damit Sie mit einer sauberen Ausgangsbasis beginnen können.

• Das Skript build entfernt Ausgabedateien früherer Builds und verwendet den TypeScript-Compiler, um das Paket im Ausgabeverzeichnis zu erstellen.

• Das Skript prepack wird von npm ausgeführt, bevor das npm-Paket für die Veröffentlichung in einer Registry gepackt wird.

6. Installieren Sie nun die erforderlichen Entwicklungsabhängigkeiten. Führen Sie dazu npm install -D typescript del-cli aus.

7. Führen Sie jetzt in Ihrem Terminal npm run build aus, damit TypeScript Ihr Projekt für die Verwendung und Veröffentlichung erstellt.

Damit ist alles eingerichtet, was Sie benötigen, um TypeScript zum Erstellen Ihres npm-Pakets zu verwenden, das sowohl das CommonJS- als auch das ECMAScript-Modulformat unterstützt. Als Nächstes erfahren Sie, wie Sie Tests für den Code Ihres npm-Pakets einrichten und ausführen, um sicherzustellen, dass er die erwarteten Ergebnisse liefert.

Tests einrichten und hinzufügen

Damit Sie sich auf das Verhalten und die Ergebnisse Ihres Codes verlassen können, müssen Sie einen Testprozess implementieren. Tests regen Sie dazu an, die Funktionalität Ihres Codes aus verschiedenen Blickwinkeln zu betrachten – auch abseits des typischen „Happy Path“, den Sie bei der ersten Entwicklung im Sinn haben. Überlegen Sie zum Beispiel, wie Sie eine Funktion dazu bringen können, einen Fehler auszulösen oder ein unerwünschtes Ergebnis zu liefern. So wird Ihre Anwendung robuster und nachhaltiger. Außerdem stellen Sie sicher, dass beim Hinzufügen neuer Funktionen nichts kaputtgeht.

Wenn Sie tiefer in das Thema Testing einsteigen und mehr über Best Practices erfahren möchten, lesen Sie unbedingt Yoni Goldbergs JavaScript-Best-Practices-Repository.

Unit-Tests

Damit sichergestellt ist, dass sich Ihr Paket wie gewünscht verhält, müssen Sie Tests für Ihren Code schreiben. Für die Einrichtung Ihres Projekts zum Ausführen von Unit-Tests und Anzeigen der Ergebnisse benötigen Sie einige Tools. Diese Tools sind inzwischen als integrierte Module in Node.js verfügbar (seit Version 20.x und 18.x sowie 16.17.x hinter einem experimentellen Flag). Folgen Sie den nachstehenden Schritten, um Tests für Ihr npm-Paket einzurichten und auszuführen:

1.  Installieren Sie die Entwicklungsabhängigkeiten mit folgendem Befehl in Ihrem Terminal: npm i -D @types/node

2. Erstellen Sie im Stammverzeichnis Ihres Projekts einen Ordner tests.

3. Erstellen Sie im Ordner tests eine Datei index.test.ts.

4. Schreiben Sie Unit-Tests in die Datei index.test.ts, um den Code in index.ts zu testen.

Hinweis: Als Beispiel können Sie sich das Repository mit dem Beispiel-npm-Paket ansehen: https://github.com/snyk-snippets/modern-npm-package.

5. Fügen Sie im Abschnitt scripts Ihrer Datei package.json eine Eigenschaft tests hinzu und weisen Sie ihr den Wert node --experimental-strip-types --test zu.

1  "scripts": {
2     "clean": "del-cli ./lib",
3    "build": "npm run clean && tsc -p ./tsconfig.json",
4    "prepack": "npm run build",
5    "test": "node --experimental-strip-types --test",
6
7  },

6. Führen Sie im Stammverzeichnis des Projekts in Ihrem Terminal npm test aus, um Ihre Tests auszuführen und die Ergebnisse anzuzeigen:

1> @snyk-labs/modern-npm-package@0.0.0-development test
2> node --experimental-strip-types --test
3
4(node:83429) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
5(Use `node --trace-warnings ...` to show where the warning was created)
6(node:83430) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
7(Use `node --trace-warnings ...` to show where the warning was created)
8▶ NPM Package
9  ✔ should be an object (0.754083ms)
10  ✔ should have a helloWorld property (0.518958ms)
11✔ NPM Package (1.754875ms)
12▶ Hello World Function
13  ✔ should be a function (0.136667ms)
14  ✔ should return the hello world message (0.063791ms)
15✔ Hello World Function (0.270417ms)
16▶ Goodbye Function
17  ✔ should be a function (0.13275ms)
18  ✔ should return the goodbye message (0.159541ms)
19✔ Goodbye Function (0.552542ms)
20ℹ tests 6
21ℹ suites 3
22ℹ pass 6
23ℹ fail 0
24ℹ cancelled 0
25ℹ skipped 0
26ℹ todo 0
27ℹ duration_ms 113.692542

Tests in einer Pipeline

Da Sie jetzt Tests haben, mit denen Sie das Verhalten Ihres Codes prüfen können, können Sie diese in einer Pipeline einsetzen. So stellen Sie sicher, dass keine Änderungen an Ihrem Repository das Verhalten des Codes beeinträchtigen. Folgen Sie den nachstehenden Schritten, um einen Test-Workflow als Teil Ihrer Projekt-Pipeline zu erstellen.

1. Erstellen Sie für Ihr Repository eine neue GitHub Action: https://github.com/<your-account-or-organization>/<your-repo-name>/actions/new

2. Benennen Sie den Workflow in tests.yml um.

3. Fügen Sie das folgende Snyk-GitHub-Action-Skript in Ihre Workflow-Datei ein:

1name: Tests
2
3on:
4  push:
5    branches: [ main ]
6  pull_request:
7    branches: [ main ]
8
9jobs:
10  build:
11
12    runs-on: ubuntu-latest
13
14    strategy:
15      matrix:
16        node-version: [22.x]
17
18    steps:
19      - uses: actions/checkout@v4
20      - name: Use Node.js ${{ matrix.node-version }}
21        uses: actions/setup-node@v4
22        with:
23          node-version: ${{ matrix.node-version }}
24      - run: npm ci
25      - run: npm test

Dieses YAML-Skript ruft Ihren aktuellen Code ab, installiert dessen Abhängigkeiten und führt den Befehl npm test aus, um Ihre Tests auszuführen. Das Skript durchläuft dabei jede Node.js-Version, die im Feld node-version aufgeführt ist. So können Sie sicherstellen, dass der Code in jeder Runtime wie erwartet funktioniert.

Sie haben Ihr Projekt jetzt so eingerichtet, dass Sie Tests für den Code Ihres npm-Pakets ausführen und auswerten können. Vielleicht fragen Sie sich jedoch: „Wie teste ich die Verwendung meines npm-Pakets in einem anderen Projekt?“ Sehen wir uns als Nächstes an, wie Sie dabei vorgehen können.

Paket testen

Es ist eine Sache, dank Unit-Tests Vertrauen in den Code Ihres npm-Pakets zu haben. Eine andere ist es, sicherzustellen, dass sich das gesamte npm-Paket in der Anwendung wie erwartet verhält. Dazu integrieren Sie Ihr npm-Paket als Abhängigkeit in ein anderes Projekt und prüfen, ob es dort wie erwartet funktioniert. Hier sind fünf Möglichkeiten, das zu testen:

1. Installation über die Ausgabe von npm pack

2. Installation über einen relativen Pfad

3. Installation über npm link

4. Installation über eine Registry (z. B. die öffentliche npm-Registry unter npmjs.com)

5. Verwenden Sie Verdaccio (ein Open-Source-Projekt für private npm-Registries), um im Rahmen Ihrer CI End-to-End-Schritte zum Veröffentlichen und Installieren von Paketen auszuführen

npm pack

Bei diesem Ansatz wird der Befehl npm pack verwendet, um Ihr npm-Paket zu bündeln und in einer einzelnen Datei zu komprimieren (<package-name>.tgz). Anschließend können Sie zum Projekt wechseln, in dem Sie das Paket verwenden möchten, und es über diese Datei installieren. Gehen Sie dazu wie folgt vor:

1. Führen Sie im Verzeichnis Ihres npm-Pakets im Terminal npm pack aus. Notieren Sie sich die erzeugte .tgz-Datei und ihren Speicherort.

2. Wechseln Sie in das Projektverzeichnis, in dem Sie das npm-Paket verwenden möchten. Beispiel: cd /path/to/project

3. Führen Sie im Projektverzeichnis client den Befehl npm install /path/to/package.tgz aus. Ersetzen Sie den Pfad durch den tatsächlichen Speicherort der .tgz-Datei aus Schritt 1.

4. Anschließend können Sie das Paket im client-Projekt verwenden und testen.

So erhalten Sie eine möglichst produktionsnahe Erfahrung bei der Verwendung Ihres npm-Pakets.

npm link

Bei diesem Ansatz wird mit dem Befehl npm link auf Ihr Paketverzeichnis verwiesen, wenn Sie versuchen, das Paket in client-Projekten zu installieren. Gehen Sie dazu wie folgt vor:

1. Führen Sie im Verzeichnis Ihres npm-Pakets im Terminal den Befehl npm link aus.

2. Wechseln Sie in das Projektverzeichnis, in dem Sie das npm-Paket verwenden möchten. Beispiel: cd /path/to/project

3. Führen Sie im Projektverzeichnis client den Befehl npm link <name-of-your-package> aus.

Dadurch verweist Ihr client-Projekt bei der Verwendung des Pakets in Ihrem Code auf das npm-Paketverzeichnis. Sie erhalten damit zwar keine vollständig produktionsnahe Erfahrung, können aber sicherstellen, dass die Funktionalität wie erwartet funktioniert.

Relativer Pfad

Bei diesem Ansatz nutzen Sie Ihre vorhandenen Kenntnisse des Befehls npm install. Er ähnelt npm link, ohne dass Sie einen neuen Befehl wie link kennen müssen.

1. Führen Sie im Projektverzeichnis client im Terminal den Befehl npm install /path/to/your/package aus.

Ähnlich wie beim Ansatz mit npm link können Sie damit die Funktionalität Ihres Pakets schnell in einem Client-Projekt testen. Eine vollständig produktionsnahe Erfahrung erhalten Sie jedoch nicht. Denn dabei wird auf das gesamte Quellcodeverzeichnis des Pakets verwiesen und nicht auf eine gebaute Version des Pakets, wie Sie sie in einer npm-Registry finden.

npm-Registry

Bei diesem Ansatz verwenden Sie die öffentliche oder eine eigene Registry für npm-Pakete. Dazu veröffentlichen Sie Ihr Paket und installieren es wie jedes andere npm-Paket.

1. Veröffentlichen Sie Ihr npm-Paket mithilfe der zuvor in diesem Artikel beschriebenen Schritte und des Befehls npm publish.

2. Wechseln Sie in das Projektverzeichnis, in dem Sie das npm-Paket verwenden möchten. Beispiel: cd /path/to/project

3. Führen Sie im Projektverzeichnis client den Befehl npm install <name-of-your-package> aus.

Ein großes Dankeschön an Mirco Kraenz (@MKraenz), der in einem Twitter-Thread unsere Erkenntnisse aus einem Livestream zusammengefasst hat!

Sie haben Ihr Paket nun so aufgebaut, dass es moderne Modulformate unterstützt, und mit Unit-Tests und Paketierungstests sichergestellt, dass es sich wie erwartet verhält. Als Nächstes müssen Sie dafür sorgen, dass Ihr npm-Paket keine Sicherheitsprobleme aufweist und keine neuen eingeführt werden.

Sicherheitsprüfungen implementieren

So wie Sie keine Sicherheitslücken in Ihren eigenen Projekten möchten, sollten Sie auch keine in die Projekte anderer einführen. Ein npm-Paket zu entwickeln, das in vielen anderen Projekten zum Einsatz kommen soll, bringt eine erhöhte Verantwortung mit sich, für Sicherheit zu sorgen. Sie benötigen Sicherheitsprüfungen, um Sicherheitslücken zu überwachen, Warnungen dazu zu erhalten und Unterstützung bei ihrer Behebung zu bekommen. Ein Tool wie Snyk kann Ihnen dabei die Arbeit erleichtern.

Für dieses Beispiel verwenden Sie GitHub als Versionsverwaltung. Deshalb nutzen Sie GitHub Actions, um Snyk in Ihren Workflow zu integrieren. Snyk bietet ein Referenzprojekt für GitHub Actions, das Ihnen den Einstieg erleichtert und Beispiele für weitere Programmiersprachen und Tools enthält, die Sie in Ihren Projekten verwenden können.

1. Snyk ist kostenlos. Registrieren Sie sich und rufen Sie Ihren Snyk API Token ab.

2. Fügen Sie Ihren Snyk API Token als Repository-Secret in GitHub hinzu: https://github.com/<your-account-or-organization>/<your-repo-name>/settings/secrets/actions/new

3. Erstellen Sie eine neue GitHub Action für Ihr Repository: https://github.com/<your-account-or-organization>/<your-repo-name>/actions/new

4. Benennen Sie den Workflow in snyk.yml um.

5. Fügen Sie das folgende Snyk-Action-Skript in Ihre Workflow-Datei ein:

1name: Snyk Security Check
2on: [push,pull_request]
3jobs:
4  security:
5    runs-on: ubuntu-latest
6    steps:
7      - uses: actions/checkout@main
8      - name: Run Snyk to check for vulnerabilities
9        uses: snyk/actions/node@master
10        env:
11          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}

6. Übernehmen Sie Ihre Änderungen.

7. Prüfen Sie, ob die Action erfolgreich ausgeführt wurde: https://github.com/<your-account-or-organization>/<your-repo-name>/actions

Nach der Einrichtung wird bei jedem Push in Ihr Repository und bei jedem Pull Request dafür eine Sicherheitsprüfung ausgeführt, um sicherzustellen, dass keine Sicherheitslücken in das Paket eingeführt werden. Wird ein Problem erkannt, schlägt die Action fehl und informiert Sie über die gefundene Sicherheitslücke. Als Nächstes automatisieren Sie die Versionierung und Veröffentlichung Ihres npm-Pakets.

Möchten Sie schon vor dem Push von Änderungen in Ihr Repository über Sicherheitsprobleme informiert werden? Installieren Sie das Snyk-Plug-in für Ihr bevorzugtes Entwicklungstool. Arbeiten Sie lieber mit CLI-Tools? Integrieren Sie auch die Snyk CLI in Ihre Toolchain. So können Sie Sicherheitsprobleme bereits während der Entwicklung erkennen und werden früher im Projekt-Workflow darauf aufmerksam gemacht.

Beachten Sie, dass diese Einrichtung derzeit nur das Produkt Snyk Open Source (SCA) nutzt und nicht Snyk Code (SAST). Snyk Code ist unser Produkt für Code-Sicherheit. Sie müssen es zunächst in Ihrem Snyk-Konto (kostenlos) aktivieren und anschließend hier in Ihr Workflow-Skript aufnehmen, um es umfassend zu nutzen. Weitere Informationen zur Verwendung von Snyk Code in Ihrer Pipeline finden Sie in diesem Artikel: Eine sichere Pipeline mit GitHub Actions erstellen (dort kommen Java und Maven zum Einsatz, die sich jedoch durch Node.js und npm ersetzen lassen).

Versionsverwaltung und Veröffentlichung automatisieren

Wenn Sie Änderungen in Ihrem Hauptbranch zusammenführen, möchten Sie die Version des npm-Pakets nicht jedes Mal manuell aktualisieren und veröffentlichen. Stattdessen können Sie diesen Prozess automatisieren. Vielleicht erinnern Sie sich an das einfache Beispiel für ein npm-Paket weiter oben in diesem Artikel: Dort haben Sie den folgenden Befehl verwendet, um Ihr npm-Paket zu veröffentlichen:

1npm publish

Außerdem sollten Sie dem Branchenstandard der semantischen Versionierung folgen, damit Nutzerinnen und Nutzer Ihres Pakets verstehen, welche Auswirkungen die verschiedenen Versionsänderungen haben, die Sie in der Registry veröffentlichen.

Was ist semantische Versionierung?

Bei der semantischen Versionierung besteht die Versionsnummer aus drei Teilen: der Hauptversionsnummer, der Nebenversion und der Patch-Version. Weitere Informationen zur semantischen Versionierung, Versionsverwaltung und Lockfiles finden Sie in Was ist Package Lock JSON und wie funktioniert eine Lockfile mit Yarn- und NPM-Paketen?

Was wäre, wenn Sie all diese Schritte nicht manuell ausführen, sondern einen automatisierten Workflow mit GitHub Actions einrichten könnten, der die Veröffentlichung Ihres npm-Pakets übernimmt? Das Tool Semantic Release lässt sich in GitHub Actions integrieren und macht genau das möglich. Der Schlüssel zur Automatisierung: Verwenden Sie beim Übernehmen von Änderungen in Ihr Projekt sogenannte Conventional Commits. So kann die Automatisierung alles entsprechend aktualisieren und die nächste Veröffentlichung Ihres Projekts vorbereiten.

Mit den folgenden Schritten richten Sie dies für Ihr modernes npm-Paket ein.

1. Führen Sie im Terminal den folgenden Befehl aus: npm i -D semantic-release

2. Führen Sie im Terminal den folgenden Befehl aus: npx semantic-release-cli setup

3. Folgen Sie den Aufforderungen im Terminal und geben Sie die benötigten Tokens an:

• Sie benötigen ein persönliches Zugriffstoken von GitHub. Rufen Sie zum Erstellen die folgende Seite auf: https://github.com/settings/tokens/new?scopes=public_repo

• Verwenden Sie beim Erstellen dieses Tokens die folgenden Berechtigungsbereiche:

• Klicken Sie auf „Generate token“ und kopieren und speichern Sie den auf der Seite angezeigten Wert.

• Außerdem benötigen Sie ein Zugriffstoken vom Typ Automation von npm. Verwenden Sie es ausschließlich in CI-Umgebungen, damit die Zwei-Faktor-Authentifizierung Ihres Kontos umgangen werden kann. Rufen Sie zum Erstellen die folgende Seite auf: https://www.npmjs.com/settings/<your-npm-account>/tokens. Wählen Sie unbedingt den Typ „Automation“ aus, da das Token in einem CI/CD-Workflow verwendet wird.

1bc@mbp-snyk modern-npm-package % npx semantic-release-cli setup
2? What is your npm registry? https://registry.npmjs.org/
3? What is vour nom username? clarkio
4? What is your pm password? [hidden]
5? What is your NPM two-factor authentication code? <2FA code>
6Provide a GitHub Personal Access Token (create a token at https://github.com/settings/tokens/new?scopes=repo
7<token>
8? What CI are you using? Github Actions
9bc@mbp-snyk modern-npm-package %

4. Fügen Sie Ihr npm-Token hier als Repository-Secret zu Ihrem GitHub-Repository hinzu: https://github.com/<your-name-or-organization>/<your-repository>/settings/secrets/actions/new. Nennen Sie das Secret NPM_TOKEN und verwenden Sie dafür den Wert, den Sie in einem vorherigen Schritt abgerufen haben.

5. Öffnen Sie in Ihrem Projekt die Datei package.json und fügen Sie wie unten gezeigt den Schlüssel releases hinzu. Wenn Ihr primärer Repository-Branch noch master statt main heißt, passen Sie den oben angegebenen Wert für branches entsprechend an.

1"release": {
2    "branches": ["main"]
3  }

6. Fügen Sie auch der Datei package.json den Schlüssel publishConfig hinzu:

1"publishConfig": {
2    "access": "public"
3 }

7. Testen Sie die Einrichtung mit einem Probelauf des npm-Skripts semantic-release. Setzen Sie im folgenden Befehl die Werte für NPM_TOKEN= und GH_TOKEN= auf Ihre jeweiligen Token. Kopieren Sie dann den vollständigen Befehl und führen Sie ihn im Terminal aus, um zu prüfen, ob alles korrekt funktioniert. Der Ablauf wird in der Terminalausgabe protokolliert. Etwaige Probleme werden dort angezeigt und mit Details zu ihrer Behebung erläutert.

8. Wenn der Probelauf erfolgreich abgeschlossen wurde, können Sie in Ihrem GitHub-Repository eine neue GitHub Action einrichten, die den Veröffentlichungsprozess übernimmt. Öffnen Sie Ihr Repository auf GitHub und klicken Sie auf „Actions“.

9. Klicken Sie auf die Option New workflow.

10. Benennen Sie den Workflow in release.yml um.

11. Fügen Sie das folgende YAML-Skript in die neue Workflow-Datei ein. Das Skript legt fest, dass der Release-Job ausgeführt wird, sobald der Snyk-Sicherheitscheck erfolgreich abgeschlossen ist. Der Release-Job ruft den Code ab, richtet eine Node.js-Umgebung ein, installiert Ihre Abhängigkeiten und führt anschließend Semantic Release mit Ihren GitHub- und npm-Tokens aus.

1name: Release
2on:
3  workflow_run:
4    workflows: ['Snyk Security Check', 'Tests']
5    branches: [main]
6    types:
7      - completed
8
9permissions:
10  contents: read
11
12jobs:
13  release:
14    name: Release
15    runs-on: ubuntu-latest
16    permissions:
17      contents: write # to be able to publish a GitHub release
18      issues: write # to be able to comment on released issues
19      pull-requests: write # to be able to comment on released pull requests
20      id-token: write
21    steps:
22      - name: Checkout
23        uses: actions/checkout@v4
24        with:
25          fetch-depth: 0
26      - name: Setup Node.js
27        uses: actions/setup-node@v4
28        with:
29          node-version: 'lts/*'
30      - name: Install dependencies
31        run: npm ci
32      - name: Verify the integrity of provenance attestations and registry signatures for installed dependencies
33        run: npm audit signatures
34      - name: Release
35        env:
36          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
37          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
38        run: npx semantic-release

Dieses Skript legt fest, dass der Release-Job ausgeführt wird, sobald der Snyk-Sicherheitscheck und die Tests erfolgreich abgeschlossen sind. Der Release-Job ruft den Code ab, richtet eine Node.js-Umgebung ein, installiert Ihre Abhängigkeiten und führt anschließend Semantic Release mit Ihren GitHub- und npm-Tokens aus.

• Hinweis: GitHub Actions enthält bereits ein Secret bzw. eine Umgebungsvariable namens GITHUB_TOKEN. Sie müssen in dieser Umgebung also kein persönliches Zugriffstoken angeben. Das persönliche Zugriffstoken (PAT) benötigen Sie nur, um Ihre Semantic-Release-Konfiguration lokal zu testen.

12. Übernehmen Sie Ihre lokalen Änderungen und pushen Sie sie in Ihr GitHub-Repository.

• Führen Sie dazu im Terminal den Befehl git commit -am '<your commit message>' und anschließend git push aus.

• Sie können dies auch in VS Code über die Versionskontrollfunktion erledigen.

13. Nachdem Sie alles eingerichtet haben, können Sie jetzt Conventional Commits verwenden, um Änderungen in Ihren Main-Branch zu übertragen (oder Pull Requests zusammenzuführen). Daraufhin wird der Release-Workflow ausgeführt (nach dem Snyk-Sicherheitstest natürlich). Ein Beispiel dafür finden Sie im Workflow des modern-npm-package-Repositorys.

Kontinuierliche Sicherheitsüberwachung mit Snyk über GitHub

Sicherheitsprüfungen direkt in den Prozess zu integrieren, in dem Sie Ihren Code committen, ist zwar vorteilhaft, doch besteht die Gefahr, dass Schwachstellen übersehen werden, die zwischen Commits auftreten. Wenn Sie beispielsweise seit einigen Monaten keinen Code mehr in Ihr Repository übertragen haben, erfahren Sie möglicherweise nichts von neuen Schwachstellen, die in dieser Zeit entdeckt wurden. Hier unterstützt Snyk Sie zusätzlich: Wenn Sie Ihr GitHub-Repository mit Snyk verbinden, überwacht Snyk es automatisch auf neue Schwachstellen und benachrichtigt Sie darüber – unabhängig davon, wie oft Sie an dem Projekt programmieren. Darüber hinaus erstellt Snyk automatisierte Pull Requests, um die Sicherheitsprobleme für Sie zu beheben.

Zwei Snyk-Produkte sind besonders hilfreich, um die Sicherheit Ihres npm-Paketcodes und seiner Abhängigkeiten zu gewährleisten. Snyk Code unterstützt Sie dabei, Ihren Paketcode abzusichern, und Snyk Open Source überwacht Ihre Open-Source-Abhängigkeiten auf Schwachstellen.

Führen Sie die folgenden Schritte aus, um Ihr kostenloses Snyk-Konto optimal zu nutzen:

1. Melden Sie sich bei Ihrem kostenlosen Snyk-Konto an

2. Wählen Sie Add project und anschließend GitHub aus.

3. Suchen Sie anhand des Namens nach dem Repository Ihres Projekts und aktivieren Sie das Kontrollkästchen daneben.

4. Vergewissern Sie sich, dass das Repository erfolgreich in Snyk importiert wurde.

Erstellen Sie moderne npm-Pakete

Fassen wir zusammen, was Sie in diesem Artikel gelernt haben. Zunächst haben Sie sich mit der Einrichtung, Erstellung und Bereitstellung eines einfachen npm-Pakets vertraut gemacht. So konnten Sie sich damit vertraut machen, was bei der erstmaligen Veröffentlichung eines eigenen npm-Pakets erforderlich ist. Für ein npm-Paket, das produktiv eingesetzt werden soll, ist dieses Vorgehen jedoch recht aufwendig und nicht nachhaltig.

Um ein produktionsreifes Paket zu erstellen, haben Sie anschließend gelernt, wie Sie Module sowohl im CommonJS- (CJS) als auch im ECMAScript-Modulformat (ESM) erstellen, Unit-Tests einrichten und schreiben, Sicherheitsprüfungen implementieren sowie Versionsverwaltung und Veröffentlichung automatisieren. Mit diesem Wissen können Sie jetzt zahlreiche weitere npm-Pakete erstellen, die sich von der Community oder Ihrem Unternehmen problemlos nutzen lassen.

Testen Sie Snyks kostenlosen JavaScript-Code-Checker, um Schwachstellen in Ihrem Code zu finden und zu beheben.