npm-Befehle: Ratgeber zur Paketverwaltung

01Was ist npm und wofür braucht man es?

npm (Node Package Manager) ist der Paketmanager der JavaScript-Welt. Damit binden Sie Bibliotheken anderer Entwickler in Ihr Projekt ein, behalten deren Versionen im Blick und führen projektbezogene Befehle an einer zentralen Stelle aus.

npm wird mit Node.js geliefert, Sie müssen es nicht gesondert installieren. Haben Sie Node.js noch nicht installiert, folgen Sie zuerst unserer Anleitung zur Node.js-Installation und probieren die Befehle dieses Beitrags dann in Ihrem eigenen Terminal aus.

npm besteht aus drei Teilen: dem Kommandozeilen-Tool auf Ihrem Rechner, der Registry, in der die Pakete liegen, und der Datei package.json, dem Herzstück jedes Projekts. Fast alle Befehle lesen diese Datei oder aktualisieren sie.

02Was ist die package.json?

Die package.json ist der Steckbrief des Projekts: Name, Version, Abhängigkeiten und ausführbare Skripte stehen hier. In einem neuen Projekt erzeugen Sie die Datei mit npm init; mit dem Flag -y werden alle Fragen mit den Standardwerten beantwortet.

• dependencies: Pakete, die die Anwendung zur Laufzeit braucht.
• devDependencies: Werkzeuge, die nur für Entwicklung und Build nötig sind (Compiler, Testtool, Formatierer).
• scripts: Kurzbefehle, die mit npm run ausgeführt werden.
• package-lock.json: Hält die exakte Version jedes installierten Pakets fest; nehmen Sie diese Datei unbedingt in Git auf.

mkdir ilk-proje
cd ilk-proje
npm init -y

{
  "name": "ilk-proje",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "node --test"
  },
  "dependencies": {
    "axios": "^1.7.0"
  },
  "devDependencies": {
    "vite": "^6.0.0"
  }
}

03Pakete installieren mit npm install

npm install ist der am häufigsten genutzte Befehl und erledigt zwei verschiedene Aufgaben. Ohne Zusatz installiert er alle Abhängigkeiten aus der package.json in den Ordner node_modules; mit einem Paketnamen installiert er dieses Paket und trägt es in die package.json ein. Die Kurzform lautet npm i.

# Alle Abhängigkeiten des Projekts installieren
npm install

# Yeni paket ekle (dependencies)
npm install axios

# Entwicklungswerkzeug hinzufügen (devDependencies)
npm install -D prettier

# Bestimmte Version installieren
npm install lodash@4

# Globale Installation (für Kommandozeilentools)
npm install -g serve

# Paket entfernen
npm uninstall axios

Global oder lokal?

Installieren Sie Pakete möglichst lokal; so läuft das Projekt auch auf einem anderen Rechner mit derselben Version. Reservieren Sie die globale Installation nur für Kommandozeilen-Tools, die Sie überall nutzen, und für einmalige Tools genügt npx.

Wann nutzt man npm ci?

npm ci löscht den Ordner node_modules und installiert exakt die Versionen aus der package-lock.json, ohne die Lock-Datei zu verändern. Ideal für das Deployment auf Servern, für Continuous-Integration-Pipelines und um Probleme nach dem Muster »Bei mir lief es noch« zu lösen.

04Skripte ausführen mit npm run

Das Feld scripts in der package.json erlaubt es, langen Befehlen kurze Namen zu geben. So startet jeder im Team, ohne die Details des Tools zu kennen, mit npm run dev den Entwicklungsserver und mit npm run build den Produktions-Build.

Einige Namen wie start und test sind besonders; sie laufen auch ohne run. Zusätzliche Parameter an ein Skript übergeben Sie mit zwei Bindestrichen.

npm run dev
npm run build
npm start
npm test

# Alle definierten Skripte auflisten
npm run

# Parameter an das Skript übergeben
npm run build -- --mode staging

pre- und post-Skripte

Setzen Sie vor den Namen eines Skripts pre oder post, führt npm es automatisch davor oder danach aus. Ein Skript namens prebuild kann zum Beispiel direkt vor npm run build den alten Build-Ordner aufräumen. So vergisst im Team niemand einen Schritt.

Warum finden Skripte lokale Tools?

npm run fügt während der Ausführung den Ordner node_modules/.bin des Projekts vorübergehend zum PATH hinzu. Deshalb genügt es, im Skript nur vite oder prettier zu schreiben; das Tool muss nicht global installiert sein. Wird dasselbe Tool im Terminal direkt nicht gefunden, liegt es daran, und die Lösung ist npx.

Unterschiede zwischen Betriebssystemen in Skripten

Befehle wie rm -rf funktionieren in der Standard-Shell von Windows nicht. Arbeiten im Team verschiedene Betriebssysteme, verwenden Sie in Skripten besser plattformunabhängige Node.js-Tools oder kurze Node.js-Skripte; so liefert dieselbe package.json auf jedem Rechner dasselbe Ergebnis.

05Pakete aktualisieren und prüfen

Pakete werden regelmäßig aktualisiert: Sicherheitslücken werden geschlossen, neue Funktionen kommen hinzu. Um vor dem Update zu sehen, was veraltet ist, führen Sie den Befehl npm outdated aus.

Das Zeichen ^ in der package.json erlaubt Minor- und Patch-Versionen (1.7.0 → 1.9.2), das Zeichen ~ nur Patch-Versionen (1.7.0 → 1.7.5). npm update aktualisiert innerhalb dieser Grenzen; für einen Sprung auf eine neue Hauptversion müssen Sie das Paket mit @latest neu installieren, und das erfordert meist Änderungen am Code.

# Eskiyen paketleri listele
npm outdated

# Im erlaubten Versionsbereich aktualisieren
npm update

# Auf die nächste Hauptversion wechseln (mit Vorsicht)
npm install axios@latest

# Sicherheitsprüfung
npm audit
npm audit fix

# Installierte Pakete anzeigen
npm ls --depth=0
npm ls -g --depth=0

# Neueste veröffentlichte Version eines Pakets
npm view axios version

06Was ist npx und wann nutzt man es?

npx ist ein Paketausführer, der mit npm geliefert wird. Damit führen Sie ein Tool einmalig aus, ohne es global zu installieren; das Tool wird zuerst im Ordner node_modules des Projekts gesucht und, falls es dort fehlt, vorübergehend heruntergeladen.

Der häufigste Einsatz von npx ist das Erzeugen von Projektvorlagen. Um etwa mit Vite ein neues React-Projekt anzulegen, nutzen Sie den Befehl npm create; Einzelheiten finden Sie in unserem Beitrag zur React-Installation mit Vite.

# Ordner auf dem lokalen Server bereitstellen
npx serve .

# Im Projekt installierten Formatter ausführen
npx prettier --write .

# Neues Projekt aus einer Vorlage (entspricht npm create bzw. npx create-...)
npm create vite@latest

07Der Unterschied zwischen npm, yarn und pnpm

npm ist nicht die einzige Option; auch yarn und pnpm installieren Pakete über dieselbe Registry. Da alle drei die package.json nutzen, bleibt die Projektstruktur gleich; Unterschiede zeigen sich bei Installationsgeschwindigkeit, Speicherbedarf und Lock-Datei.

• Verwenden Sie in einem Projekt nur einen Paketmanager; zwei Lock-Dateien gleichzeitig führen zu Versionschaos.
• Steigen Sie in ein bestehendes Projekt ein, schauen Sie auf die Lock-Datei im Ordner und wählen Sie dasselbe Tool.
• Fangen Sie gerade erst an, ist der Start mit npm der Weg mit der geringsten Reibung.

08Häufige Fehler und Lösungen

Die meisten npm-Fehler entstehen durch einen defekten Cache, eine inkompatible Node.js-Version oder kollidierende Abhängigkeiten. Lesen Sie zuerst die ersten Zeilen der Fehlermeldung; die Lösung steht meist dort.

• ERESOLVE / Peer-Dependency-Fehler: Eines der Pakete erwartet eine andere Version eines anderen Pakets. Aktualisieren Sie die Pakete auf kompatible Versionen; vorübergehend lässt sich npm install --legacy-peer-deps nutzen.
• Defekter node_modules-Ordner: Löschen Sie den Ordner node_modules und führen Sie npm install oder npm ci aus. Die Lock-Datei zu löschen ist der letzte Ausweg.
• Cache-Problem: npm cache verify prüft den Cache; bei Bedarf leeren Sie ihn mit npm cache clean --force.
• EACCES-Berechtigungsfehler: Verwenden Sie bei der globalen Installation kein sudo; installieren Sie Node.js stattdessen mit nvm neu.
• Engine-Warnung: Verlangt ein Paket ein neueres Node.js, wechseln Sie mit nvm auf die LTS-Version.

09npm richtig in Projekten einsetzen

Zu viele Pakete erhöhen sowohl das Sicherheitsrisiko als auch die JavaScript-Menge, die die Seite an den Browser schickt. Vor jeder neuen Abhängigkeit zu fragen »Lässt sich das mit ein paar Zeilen Code lösen?«, ist die günstigste Optimierung für die Seitengeschwindigkeit. Dieses Thema behandeln wir regelmäßig in unserer Speed- und Performance-Optimierung.

Nehmen Sie den Ordner node_modules niemals in Git auf; tragen Sie ihn in die .gitignore ein und teilen Sie nur die package.json und die Lock-Datei. Wie Sie ein Projekt in ein Remote-Repository hochladen, haben wir in der Anleitung Projekt auf GitHub hochladen Schritt für Schritt beschrieben.

Planen Sie für Ihr Unternehmen ein Webdesign-Projekt oder eine Integration, die Zahlungs-, Versand- und Buchhaltungssysteme miteinander verbindet, senkt eine von Anfang an saubere Abhängigkeitsverwaltung langfristig die Wartungskosten. Weitere Inhalte rund um Node.js finden Sie auf der Seite zum Tag nodejs.