Auf npm veröffentlichen und semantische Versionierung

Führen Sie vor der Veröffentlichung immer npm publish --dry-run aus. Dadurch wird die Veröffentlichung simuliert, ohne tatsächlich etwas hochzuladen. Sie sehen genau, welche Dateien enthalten wären, wie groß sie sind und welchen Inhalt das Paket-Tarball hätte. So werden häufige Fehler erkannt, etwa versehentlich eingeschlossene Quelldateien oder ein fehlendes dist-Verzeichnis.

Steuern Sie mit dem Feld files in package.json, was veröffentlicht wird: "files": ["dist", "README.md"]. Dieser Whitelist-Ansatz ist sicherer als .npmignore, das als Blacklist funktioniert und versehentlich vertrauliche Dateien offenlegen kann, wenn Sie vergessen, sie hinzuzufügen. Schließen Sie immer dist, Typdeklarationen und Dokumentation ein. Schließen Sie niemals src, Tests oder node_modules ein.

npm-Pakete folgen der semantischen Versionierung (semver): MAJOR.MINOR.PATCH. Erhöhen Sie MAJOR bei inkompatiblen Änderungen, etwa beim Entfernen von Props oder beim Ändern von API-Signaturen. Erhöhen Sie MINOR bei neuen rückwärtskompatiblen Funktionen, etwa neuen Komponenten oder neuen optionalen Props. Erhöhen Sie PATCH bei rückwärtskompatiblen Fehlerbehebungen. Versionen im Format 0.x.x gelten als noch nicht stabil; hier kann sich alles ändern.

Vorabversionskennungen zeigen an, dass eine Version noch nicht für den Produktionseinsatz bereit ist: 1.0.0-alpha.1 für frühe experimentelle Builds, 1.0.0-beta.2 für funktionsvollständige, aber möglicherweise fehlerhafte Versionen und 1.0.0-rc.1 (Release Candidate) für Versionen, die für den abschließenden Test bereit sind. Veröffentlichen Sie Vorabversionen mit npm publish --tag beta, damit sie nicht zur standardmäßig installierten Version werden.

Changesets ist das Standardtool zur Verwaltung von Paketversionen und Changelogs in Komponentenbibliotheken. Im Workflow führen Mitwirkende yarn changeset add aus, um zu dokumentieren, was sich geändert hat und welcher Änderungstyp vorliegt (major/minor/patch). Die CI führt yarn changeset version aus, um die Paketversionen zu erhöhen. Bei der Veröffentlichung wird mit yarn changeset publish nach npm veröffentlicht.

Changesets generiert und pflegt CHANGELOG.md automatisch auf Grundlage der von Mitwirkenden eingereichten Changeset-Dateien. Jeder Eintrag enthält die Versionsnummer, das Veröffentlichungsdatum und eine Beschreibung der Änderungen. So entsteht eine für Menschen lesbare Historie jeder Version, ohne dass der Changelog manuell gepflegt werden muss.

semantic-release ist ein vollständig automatisiertes Tool für die Versionierung. Es ermittelt die nächste Version aus Conventional-Commit-Nachrichten (feat: → minor, fix: → patch, BREAKING CHANGE: → major). Es erhöht die Version, generiert den Changelog und veröffentlicht nach npm – alles wird von der CI beim Zusammenführen in main ausgelöst. Eine manuelle Verwaltung von Versionen ist nicht erforderlich.

Pakete ohne Scope (my-component) sind immer öffentlich. Pakete mit Scope (@myorg/my-component) sind standardmäßig eingeschränkt (privat). Veröffentlichen Sie sie mit npm publish --access public öffentlich. Für eingeschränkte Pakete benötigen Sie ein kostenpflichtiges npm-Konto oder eine Organisation. Überprüfen Sie die Zugriffseinstellungen vor Ihrer ersten Veröffentlichung.

npm Provenance verknüpft Ihr veröffentlichtes Paket auf überprüfbare Weise mit dem zugehörigen Git-Commit. Aktivieren Sie dies in GitHub Actions mit npm publish --provenance. Nutzer können überprüfen, ob das installierte Paket aus genau dem Quell-Commit erstellt wurde, der auf der npm-Registry-Seite angezeigt wird. Dadurch wird die Sicherheit der Software-Lieferkette deutlich verbessert.

Wenn eine Version einen kritischen Fehler oder eine inkompatible Änderung enthält, markieren Sie sie als veraltet: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". npm zeigt allen Personen, die diese Version installieren, eine Warnung zur veralteten Version an. Die Version wird dadurch nicht entfernt (npm löscht veröffentlichte Versionen standardmäßig nicht), aber Nutzer werden auf ein Upgrade hingewiesen.

Pakete mit Scope verwenden das Format @scope/package-name. Der Scope ist normalerweise Ihr npm-Benutzername oder der Name Ihrer Organisation. Pakete mit Scope machen deutlich, wer das Paket pflegt, und verhindern Namenskonflikte mit Paketen ohne Scope. Verwenden Sie Pakete mit Scope für private Pakete sowie für Open-Source-Pakete, die Ihrer Organisation zugeordnet sind.

Wann sollten Sie gemäß der semantischen Versionierung die MAJOR-Versionsnummer erhöhen?

Verwenden Sie npm publish --dry-run als Vorschau und das Feld files, um zu steuern, was veröffentlicht wird. Semantische Versionierung: MAJOR für inkompatible Änderungen, MINOR für neue Funktionen, PATCH für Fehlerbehebungen. Vorabversionen verwenden die Tags -alpha/-beta/-rc. Changesets automatisiert die Versionierung und die CHANGELOG-Generierung für gemeinsam entwickelte Bibliotheken. semantic-release automatisiert die Abläufe auf Grundlage von Conventional Commits. Aktivieren Sie --provenance für die Sicherheit der Software-Lieferkette. Markieren Sie fehlerhafte Versionen mit npm deprecate als veraltet.