Was npm install wirklich bewirkt: Registry, package.json und Lockdateien

Fast jedes JavaScript-Projekt, egal ob es unter Node.js, React oder Next.js läuft, beginnt mit derselben Anweisung, und viele Entwickler führen sie täglich aus, ohne genau zu wissen, was sie bewirkt. Zu wissen, wo die Pakete herkommen, wie npm entscheidet, was installiert werden soll, und wofür package.json, package-lock.json und node_modules jeweils dienen, erleichtert das Debuggen von fehlerhaften Installationen. Diese Anleitung behandelt jeden Aspekt, vom ersten Installieren bis hin zum Veröffentlichen Ihres eigenen Pakets.

Die Befehle, die jeder eingibt

Die am häufigsten verwendete Form installiert alles, was ein Projekt bereits deklariert hat:

npm install

Ebenso verbreitet ist das Hinzufügen einer Bibliothek nach ihrem Namen, wie zum Beispiel des Express-Web-Frameworks:

npm install express

oder des Axios-HTTP-Clients:

npm install axios

Hinter diesen Einzeilkommandos verbergen sich einige Fragen. Wo wird der Code heruntergeladen? Wie weiß npm, worauf ein Projekt angewiesen ist? Wozu dient package.json? Und warum wird node_modules so groß?

Was npm ist

npm ist der Standard-Paketmanager für Node.js und wird mit ihm geliefert. Er gibt Ihnen Zugang zu einem umfangreichen Katalog wiederverwendbarer Pakete, die von anderen Entwicklern veröffentlicht wurden, sodass Sie bewährten Code in Ihr Projekt einbinden können, anstatt ihn selbst zu schreiben.

Betrachten Sie es als eine öffentliche Bibliothek für Code. Angenommen, ein Node.js-Backend benötigt einen HTTP-Server. Anstatt Routing und Middleware von Grund auf zu entwickeln, fügen Sie Express hinzu:

npm install express

Möchten Sie andere APIs aufrufen? Fügen Sie einen HTTP-Client hinzu:

npm install axios

Die Validierung eingehender Daten gegen ein Schema wird von Zod übernommen:

npm install zod

Und bcrypt kümmert sich um das Hashen von Passwörtern:

npm install bcrypt

Das ist die größte Stärke des Ökosystems: Wenn es eine gut getestete Lösung gibt, gibt es selten einen Grund, eigene zu entwickeln. Andererseits ist jedes installierte Paket Code, dem man vertrauen muss – daher sollten bevorzugt gewartete, weit verbreitete Bibliotheken verwendet werden und die Liste sollte übersichtlich bleiben. Siehe wie npm-Supply-Chain-Angriffe funktionieren, um zu verstehen, warum das wichtig ist.

Ein Ökosystem – nicht nur ein Befehl

Anfänger betrachten npm oft nur als einen Begriff, der in die Terminal eingetippt wird. Tatsächlich umfasst der Name mehrere miteinander verbundene Komponenten:

• Das npm-Registry: der öffentliche Dienst, über den Pakete veröffentlicht und heruntergeladen werden.
• Die npm CLI: das Kommandozeilenwerkzeug, das mit der Registry kommuniziert und Abhängigkeiten verwaltet.

Pakete: die wiederverwendbaren Code-Einheiten selbst.

package.json: die Manifest-Datei, die Ihr Projekt sowie seine Abhängigkeiten beschreibt.

Öffentliche Pakete sind kostenlos: Sie können beliebige öffentliche Pakete ohne Konto installieren. Diese geringe Hürde trug dazu bei, dass JavaScript unter Open Source weltweit verbreitet wurde. Ein Konto ist nur zum Veröffentlichen erforderlich.

Was passiert, wenn Sie npm install ausführen

Nehmen wir ein Projekt, das Express hinzufügt:

npm install express

Im Groben:

1. npm sucht das Paket im Registry-System und wählt eine Version aus, die in den angeforderten Bereich passt (die neueste, falls kein Bereich angegeben ist).
2. Es löst die eigenen Abhängigkeiten des Pakets sowie deren Abhängigkeiten in einem vollständigen Baum auf.
3. Es lädt alles herunter, was noch nicht im Cache gespeichert ist, und legt es in node_modules ab.

Es speichert die Abhängigkeit in package.json sowie den genauen gelösten Baum in package-lock.json.

So führt ein einziger kurzer Befehl zu einem ganzen Baum an Funktionalitäten.

package.json: die Manifest-Datei des Projekts

Eine Datei steht im Zentrum jedes Node.js-Projekts:

package.json

Sie dient gleichzeitig als Identitätskarte und Konfigurationsdatei des Projekts, enthält den Namen, die Version, Beschreibung, Skripte, Laufzeit- und Entwicklungsabhängigkeiten sowie Angaben zum Autor. Ein minimales Beispiel definiert eine Eingabedatei in main, ein Skript sowie eine einzige Abhängigkeit:

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My Node.js application",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^5.1.0"
  }
}

name

name identifiziert das Projekt oder Paket. Wenn es veröffentlicht wird, ist dies der Name, den die Nutzer eingeben müssen, um es zu installieren – daher muss er im Registry einzigartig sein.

"name": "my-project"

version

version enthält die aktuelle Version des Pakets.

"version": "1.0.0"

Das ist besonders wichtig bei der Veröffentlichung. npm verwendet semantische Versionierung (MAJOR.MINOR.PATCH): Änderungen, die Kompatibilität brechen, erhöhen die Major-Nummer, kompatible Funktionen die Minor-Nummer und Fehlerbehebungen die Patch-Nummer.

Beschreibung

description ist eine einzeilige Zusammenfassung dessen, was das Projekt tut, und wird in den Suchergebnissen des Registries angezeigt.

"description": "My Node.js application"

Skripte

scripts definiert benannte Abkürzungen für häufig verwendete Befehle. Hier startet start die Eingabedatei:

"scripts": {
  "start": "node index.js"
}

Ohne diese Abkürzung müsste man den vollen Befehl eingeben:

node index.js

Mit dieser Abkürzung funktioniert es genauso:

npm start

Der Wert ist Konsistenz: Jeder Mitwirkende und jede CI-Aufgabe führt denselben benannten Befehl aus. Benutzerdefinierte Namen wie build werden mit npm run build ausgeführt.

Abhängigkeiten: Worauf Ihr Projekt angewiesen ist

Stellen Sie sich eine Essenslieferplattform vor. Ihr Backend könnte Folgendes verwenden:

• Express für die APIs
• Zod zur Validierung
• bcrypt zum Hashen von Passwörtern
• eine JSON Web Token-Bibliothek für die Authentifizierung
• Mongoose für MongoDB

Jedes davon ist eine Abhängigkeit. Wenn Sie eine installieren:

npm install express

npm fügt einen Eintrag in package.json hinzu:

"dependencies": {
  "express": "^5.1.0"
}

Der Bindestrich in ^5.1.0 bezeichnet einen Bereich: Jede spätere 5.x-Version ist zulässig, 6.0.0 hingegen nicht. Der Eintrag informiert alle, die das Projekt lesen, dass Express zum Laufen benötigt wird. Tools, die nur während der Entwicklung benötigt werden, wie z. B. Testausführer, kommen über npm install --save-dev in devDependencies.

Warum ein Befehl für ein ganzes Team ausreicht

Nehmen wir an, Sie treten einem Team bei und klonen dessen Repository. Niemand erwartet von Ihnen, dass Sie fünfzig Bibliotheken manuell herunterladen. Sie führen aus:

npm install

npm liest die deklarierten Abhängigkeiten und installiert sie alle. Gerade weil Paketmanager es ermöglichen, eine funktionierende Umgebung aus einer Beschreibung wiederherzustellen, sind sie unverzichtbar.

node_modules: Wo der installierte Code liegt

Nach einer Installation erscheint ein neuer Ordner:

node_modules/

Er enthält die von Ihnen angeforderten Pakete sowie alles, worauf sie angewiesen sind, weshalb er groß wird. Eine typische Struktur:

my-project/
│
├── node_modules/
├── package.json
├── package-lock.json
└── index.js

Commitzen Sie node_modules nicht in Git. Er ist groß, kann Plattform-spezifische Builds enthalten und lässt sich immer neu erzeugen. Fügen Sie ihn in .gitignore ein und commitzen Sie stattdessen diese Dateien:

package.json
package-lock.json

Jeder andere kann anschließend ausführen:

npm install

und erhält wieder dieselben Abhängigkeiten.

package-lock.json: Die genaue Aufzeichnung

Neben der Manifest-Datei befindet sich eine weitere Datei:

package-lock.json

Warum beides? Kurze Erklärung:

• package.json gibt an, was das Projekt benötigt, in der Regel als Bereiche.
• package-lock.json dokumentiert genau, was installiert wurde: jede Paketversion im gesamten Baumstruktur sowie Integritätshashes.

Da Bereiche im Laufe der Zeit auf neuere Versionen zutreffen können, sorgt die Lockdatei dafür, dass Laptops, Teammitglieder und CI auf identischen Versionen arbeiten. Committen Sie sie und verwenden Sie in CI lieber npm ci, das ausschließlich aus der Lockdatei installiert.

Npm-Befehle, die man kennen sollte

Ein Paket hinzufügen:

npm install express

Alles installieren, was das Projekt angibt:

npm install

Ein Paket aus node_modules und package.json entfernen:

npm uninstall express

Pakete auf die neuesten Versionen aktualisieren, die die Bereiche zulassen (es wird keine Major-Version übersprungen):

npm update

Geben Sie die npm-Version aus:

npm -v

Geben Sie die Node.js-Version aus:

node -v

Zeigen Sie das npm-Konto an, mit dem Sie angemeldet sind:

npm whoami

Von Nutzer zu Verleger

Auch Sie können Pakete beitragen. Veröffentlichen Sie eine nützliche Bibliothek, die andere wie jede andere installieren können:

npm install your-package

Diese Schleife hält Open Source am Leben: Sie bauen auf der Arbeit anderer auf, erstellen Ihre eigenen Werke und teilen sie wieder.

Schritt für Schritt zur Veröffentlichung

Ihr benötigen ein npm-Konto. Melden Sie sich von der Terminal an:

npm login

Bestätigen Sie, welches Konto aktiv ist:

npm whoami

Wechseln Sie in das Projekt:

cd myproject

Stellen Sie sicher, dass es eine gültige Manifest-Datei mit einem eindeutigen name und einer version gibt:

package.json

Dann veröffentlichen Sie es:

npm publish

Das Paket steht nun allen zur Verfügung. Zwei Tipps: Führen Sie zunächst npm pack --dry-run aus, um zu sehen, welche Dateien mitgeliefert werden, und erhöhen Sie bei jeder Veröffentlichung die version, da eine veröffentlichte Version nicht wiederverwendet werden kann. Prüfen Sie die aktuellen npm-Dokumente nach Anforderungen zur Konto-Sicherheit wie der Zwei-Faktor-Authentifizierung.

Wie die Komponenten zusammenpassen

Der gesamte Ablauf sieht so aus:

Developer
    ↓
npm install
    ↓
npm Registry
    ↓
Package + Dependencies
    ↓
node_modules
    ↓
package.json
    ↓
Your Application

Sie führen den Befehl aus, die CLI holt die Pakete aus dem Registry-Server, der Code landet in node_modules, das Manifest sowie die Lockdatei speichern diese Informationen, und Ihre Anwendung importiert ihn. Diese Kette ermöglicht es Entwicklern, Code effizient wiederverwenden, verwalten, teilen und veröffentlichen.

Wichtige Erkenntnisse

Npm mag wie eine Ansammlung von Terminalbefehlen erscheinen, aber sobald man weiß, was hinter diesen Befehlen vor sich geht:

npm install

Das System wird dadurch leichter verständlich. JavaScript liefert die Sprache, Node.js den Laufzeitumfeld und npm das Ökosystem zum Teilen von Code. In der Praxis:

• package.json gibt die Absicht an; package-lock.json dokumentiert die tatsächlichen Inhalte. Beide sollten gespeichert werden.
• Speichern Sie niemals node_modules.
• Mit einem Caret-Bereich lassen sich kleine und Patch-Updates durchführen, wobei npm update innerhalb dieses Bereichs bleibt.
• Verwenden Sie npm ci für präzise Installationen in Automatisierungsprozessen.
• Fügen Sie Abhängigkeiten bewusst hinzu; jede davon ist Code, dem Sie vertrauen.

Wenn Sie also das nächste Mal etwas eingeben:

npm install

denken Sie daran, dass Sie Ihr Projekt mit einem von Entwicklern auf der ganzen Welt erstellten Ökosystem verbinden.

Weitere Literatur

• Was JSON.stringify heimlich weglässt, umwandelt und sich weigert zu serialisieren — Erfahren Sie, welche JavaScript-Werte von JSON.stringify weggelassen oder verändert werden, wie toJSON, Ersatzfunktionen und Wiederherstellungsmethoden das beheben sowie wann structuredClone das bessere Werkzeug ist.
• Was async/await wirklich garantiert und was es Ihnen übrig lässt — Verstehen Sie, was await tatsächlich aussetzt, wie man serialisierte Anfragen vermeidet und warum Fehler, Abbrüche, Sortierung und Wiederholungen eine über async/await hinausgehende Gestaltung erfordern.