So erstellen und veröffentlichen Sie ein npm-Paket

Sie haben Hunderte von Paketen mit npm install installiert. Jetzt möchten Sie Ihr eigenes veröffentlichen. Der Prozess erscheint zunächst unkompliziert, bis Sie veraltete Tutorials entdecken, die Node 12, reine CommonJS-Setups und langlebige Tokens empfehlen, die in CI-Secrets gespeichert werden.

Dieser Leitfaden führt Sie durch das Erstellen und Veröffentlichen eines npm-Pakets unter Verwendung moderner, sicherer Praktiken, die auch 2025 noch korrekt sein werden. Wir erstellen ein einfaches Utility, konfigurieren es ordnungsgemäß und veröffentlichen es mit npm Trusted Publishing.

Voraussetzungen

Stellen Sie vor dem Start sicher, dass Sie Folgendes haben:

• Node.js 18 oder neuer installiert
• Einen GitHub-Account
• Grundlegende Vertrautheit mit npm als Nutzer

Initialisieren Sie Ihr ESM-First npm-Paket-Setup

Erstellen Sie ein neues Verzeichnis und initialisieren Sie Ihr Projekt:

mkdir use-toggle && cd use-toggle
npm init -y
git init

Wir erstellen einen einfachen React-Hook namens useToggle. Dieses Beispiel demonstriert die Veröffentlichung eines TypeScript-npm-Pakets mit korrekten Entry Points.

Konfigurieren Sie package.json für modernes Publishing

Ersetzen Sie Ihre package.json mit einer ordnungsgemäß konfigurierten Version:

{
  "name": "@yourusername/use-toggle",
  "version": "0.1.0",
  "description": "A simple React hook for boolean toggle state",
  "keywords": ["react", "hook", "toggle", "state"],
  "license": "MIT",
  "author": "Your Name",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/yourusername/use-toggle.git"
  },
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "files": ["dist"],
  "engines": {
    "node": ">=18"
  },
  "peerDependencies": {
    "react": ">=18"
  },
  "devDependencies": {
    "typescript": "^5.4.0",
    "react": "^18.0.0",
    "@types/react": "^18.0.0"
  },
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  }
}

Wichtige Punkte für dieses ESM-First npm-Paket-Setup:

• type: "module" deklariert ESM als Standard
• exports ersetzt das veraltete main-Feld – so löst modernes Node Entry Points auf
• files steuert, was veröffentlicht wird (nur dist/)
• engines spezifiziert Node 18+, wodurch Legacy-Kompatibilitätsprobleme vermieden werden

Richten Sie die TypeScript-Kompilierung ein

Erstellen Sie tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Erstellen Sie src/index.ts:

import { useState, useCallback } from 'react';

export function useToggle(initial = false): [boolean, () => void] {
  const [value, setValue] = useState(initial);
  const toggle = useCallback(() => setValue(v => !v), []);
  return [value, toggle];
}

Führen Sie npm run build aus, um zu kompilieren. Sie erhalten dist/index.js und dist/index.d.ts – JavaScript plus Typdeklarationen, nicht rohes TypeScript.

Sicheres npm-Paket-Publishing in 2025

Erstellen Sie Ihren npm-Account mit 2FA

1. Registrieren Sie sich auf npmjs.com
2. Aktivieren Sie sofort die Zwei-Faktor-Authentifizierung (bevorzugen Sie WebAuthn/Passkeys)
3. Alle neuen Pakete haben standardmäßig 2FA-Durchsetzung aktiviert
4. Mit dem neuen sitzungsbasierten Login-Modell erfordert die Veröffentlichung jedes Pakets – neu oder bestehend – 2FA während der Sitzung

Ihre erste manuelle Veröffentlichung

npm login erstellt jetzt einen zweistündigen Sitzungstoken. Diese Tokens:

• Erscheinen nicht in der npm-Benutzeroberfläche
• Laufen automatisch nach zwei Stunden ab
• Können nicht in CI/CD wiederverwendet werden
• Erzwingen immer 2FA vor der Veröffentlichung

Ältere Tools, die sich über den veralteten CouchDB-Endpunkt authentifizieren, erhalten während der Übergangsphase ebenfalls zweistündige Sitzungstokens.

Für Ihr erstes Release:

npm login
npm publish --access public

Das Flag --access public ist für Scoped Packages auf kostenlosen Accounts erforderlich.

Überprüfen Sie Ihr Paket unter https://www.npmjs.com/package/@yourusername/use-toggle.

npm Trusted Publishing mit CI

Alte Tutorials sagen Ihnen, Sie sollen ein NPM_TOKEN erstellen und es als Repository-Secret speichern. Dieser Ansatz ist jetzt obsolet: Klassische Tokens wurden dauerhaft widerrufen, und langlebige CI-Tokens werden nicht mehr unterstützt.

Die moderne Alternative ist npm Trusted Publishing über GitHub Actions OIDC. GitHub beweist npm seine Identität, und npm stellt automatisch kurzlebige Credentials aus – kein gespeicherter Token erforderlich.

Konfigurieren Sie Trusted Publishing

1. Gehen Sie auf npmjs.com zu Ihrem Paket → Settings → Publishing access
2. Fügen Sie einen neuen „Trusted Publisher” mit Ihren GitHub-Repository-Details hinzu

Erstellen Sie den Workflow

Fügen Sie .github/workflows/publish.yml hinzu:

name: Publish

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish --provenance --access public

Das Flag --provenance fügt eine kryptografische Attestierung hinzu, die Ihr Paket mit seinem Quell-Repository verknüpft – eine Supply-Chain-Sicherheitsfunktion, die npm 2023 eingeführt hat.

Wenn OIDC nicht verwendet werden kann (z. B. bei selbst gehosteten Runnern), erstellen Sie einen kurzlebigen granularen Zugriffstoken mit:

npm token create

Granulare Tokens können 2FA umgehen für CI-Publishing und müssen innerhalb von 90 Tagen ablaufen.

Was Sie in alten Tutorials sehen werden

Vermeiden Sie diese veralteten Muster:

• "main": "index.js" ohne exports – verwenden Sie exports für korrekte ESM-Auflösung
• Targeting Node 10/12/14 – Node 18+ wird unterstützt, aber neue Pakete sollten moderne LTS-Versionen anvisieren (Node 20 oder 22)
• Reine CommonJS-Pakete – ESM ist der Standard; liefern Sie ESM-First aus
• Permanentes NPM_TOKEN in jedem Workflow – klassische Tokens sind vollständig widerrufen; verwenden Sie tokenloses Trusted Publishing

Überprüfen vor der Veröffentlichung

Testen Sie Ihr Paket immer lokal vor der Veröffentlichung:

npm pack --dry-run

Dies zeigt genau, welche Dateien enthalten sein werden. Wenn Sie src/ oder node_modules/ sehen, muss Ihr files-Feld angepasst werden.

Fazit

Um ein npm-Paket in 2025 zu erstellen und zu veröffentlichen: Verwenden Sie ESM mit korrektem exports, kompilieren Sie TypeScript zu JavaScript mit Deklarationen, aktivieren Sie 2FA und automatisieren Sie Releases mit npm Trusted Publishing. Überspringen Sie die Legacy-Muster – sie werden Ihnen und Ihren Nutzern Kopfschmerzen bereiten.

FAQs

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.