mitmario.dev

Lockfile und node_modules

Node.js Sandbox 4 Min Lesezeit 2 BeispieleLektion 4 von 7

Nach dem ersten npm install liegen zwei neue Dinge im Projekt, der Ordner node_modules und die Datei package-lock.json, das Lockfile. Eins davon gehört ins Repository und eins nicht. Wer die beiden verwechselt, schiebt Hunderte fremder Dateien ins Repository oder nimmt dem Server die Liste, nach der er installieren soll.

Zwei Dateien, zwei Aufgaben

In der package.json steht, was ungefähr gebraucht wird. Dort steht ^1.6.9, also ein Bereich, von Menschen geschrieben und für Menschen lesbar.

Im Lockfile steht, was genau installiert war. Nicht nur deine direkten Pakete, sondern auch deren Pakete und deren Pakete, jeweils mit der exakten Version und einer Prüfsumme. Geschrieben wird es von npm, und zum Lesen ist es nicht gedacht.

In deiner package.json steht ^1.6.9, und du installierst heute 1.6.9. Erscheint nächsten Monat eine 1.7.0, bekommt dein Kollege beim Installieren die neue, denn sie passt ja in den Bereich. Ihr habt beide dieselbe package.json und trotzdem verschiedenen Code.

Mit Lockfile bekommt er 1.6.9, genau wie du.

node_modules bleibt draußen

Ein Paket, das ein Paket bleibt
{
  "name": "schlank",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "slugify": "^1.6.9"
  }
}

Bei slugify sieht die Welt harmlos aus. Ein Paket, keine weiteren Abhängigkeiten, ein Eintrag in node_modules.

Ein Paket, das viele mitbringt
{
  "name": "beispiel",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "express": "^5.2.1",
    "slugify": "^1.6.9"
  }
}

Und jetzt dasselbe mit express dazu. Aus zwei Einträgen werden über sechzig Pakete, denn jedes Paket bringt mit, was es selbst braucht. Wie viele genau, hängt am Tag. Solange Express 5.2.1 die neueste Fassung war, meldete npm install mit derselben package.json added 69 packages. Mit Express 5.3.0 sind es seit Oktober 2026 added 66 packages. Die neue Express-Version verlangt ein Unterpaket in einer neueren Fassung, und damit fielen drei doppelte Kopien weg. Ein Lockfile hätte den Stand vom ersten Mal festgehalten. Auf deinem Rechner zeigt npm ls die oberste Ebene und npm ls --all den ganzen Baum.

Schon diese zwei Pakete legen rund 600 Dateien in node_modules. In größeren Projekten werden es schnell Zehntausende, und im Repository machen sie jeden Klon langsam und jeden Diff unlesbar.

Schwerer wiegen kompilierte Teile, die manche Pakete mitbringen und die zum Betriebssystem passen müssen. Was auf deinem Rechner liegt, läuft auf dem Server vielleicht nicht.

node_modules kommt in die .gitignore und das Lockfile ins Repository. Der Ordner lässt sich jederzeit aus den beiden Dateien wiederherstellen, andersherum geht es nicht.

npm install gegen npm ci

Es gibt zwei Befehle zum Installieren, und sie tun verschiedene Dinge.

npm install hält sich an das Lockfile, solange es zu den Bereichen in der package.json passt. Kommt ein Paket dazu oder ändert sich ein Bereich, sucht es passende Versionen und schreibt das Lockfile fort. Neuere Versionen innerhalb deiner Bereiche holt erst npm update. Das ist der Befehl beim Entwickeln.

npm ci liest das Lockfile und nimmt es wörtlich. Es installiert exakt die Versionen, die dort stehen, und ändert nichts. Passen package.json und Lockfile nicht zusammen, bricht es mit einem Fehler ab, statt sich etwas auszudenken. Fehlt das Lockfile ganz, installiert es gar nichts und endet mit npm error code EUSAGE. Darunter steht, dass npm ci nur mit einer vorhandenen package-lock.json installieren kann.

Dazu löscht npm ci ein vorhandenes node_modules vorher komplett. Es baut also immer von vorn auf, statt auf Resten aufzusetzen.

Auf einem Server und in jeder CI-Pipeline läuft npm ci. Zwei Deployments desselben Commits installieren damit denselben Code.

In der Doku heißt er „clean install“. Gedacht ist er für Server und CI, richtig ist er aber überall dort, wo eine Installation reproduzierbar sein soll.

„Bei mir läuft es”

Sagt jemand diesen Satz, und im Projekt liegt kein Lockfile, ist das die erste Spur.

Ohne Lockfile ist jede Installation ein neuer Wurf. Dafür muss niemand etwas falsch gemacht haben. Es reicht, dass zwischen zwei Installationen irgendwo im Baum eine neue Patch-Version erschienen ist. In so einem Baum hängen leicht sechzig Pakete, also passiert das ständig.

Deshalb bekommt das Lockfile bei einem Merge-Konflikt auch nicht die Behandlung „ich nehme mal meine Version“. Ich löse nur die package.json von Hand und lasse danach npm install laufen. npm führt die beiden Fassungen des Lockfiles dann selbst zusammen. Wirft man das Lockfile stattdessen weg, bekommt der ganze Baum die neuesten passenden Versionen, und das ist der Wurf, vor dem die Datei schützen soll.

In der Aufgabe räumst du die .gitignore eines Projekts auf, das mit npm ci auf den Server soll.

Zum Mitnehmen

Die package.json nennt Bereiche, das Lockfile die Versionen, die wirklich installiert wurden. Ins Repository kommt das Lockfile, node_modules entsteht daraus neu, und npm ci installiert, was im Lockfile steht, ohne etwas daran zu ändern.

Jetzt du

Basis Konto, kostenlos

Zu dieser Lektion gehört eine Aufgabe. Du schreibst den Code selbst, und nach jedem Lauf sagt dir eine Prüfliste, was schon stimmt.

Dafür brauchst du das Basis Konto. Es kostet nichts, und ein Passwort gibt es auch nicht.

In diesem Kurs läuft dein Code auf einem Server. Dafür hat das Basis Konto 1 Stunde im Monat, mehr Zeit gibt es mit dem Premium Konto.

Was in dieser Lektion steckt

  • Artikel mit 2 Beispielen zum Ausprobieren

    Steht hier, ohne Konto lesbar.

  • Aufgabe, auf dem Server geprüft

    Öffnet sich mit dem Basis Konto.