mitmario.dev

Die package.json

Node.js Sandbox 4 Min Lesezeit 3 BeispieleLektion 1 von 7

Du bekommst ein fremdes Projekt mit drei Dateien und einem Paket. Als Erstes willst du wissen, wie es startet und was es braucht. Die Antwort steht in der package.json.

npm init -y legt sie an. Das -y steht für „yes“. npm fragt dann nichts und nimmt überall die Vorgabe. Heraus kommt eine package.json mit einer Handvoll Feldern, von denen die meisten dich erst einmal nicht interessieren müssen. Seit npm 11 steht in dieser Datei schon "type": "commonjs". Für die Projekte in diesem Kurs ist das die falsche Vorgabe, und ein import endet damit wieder mit SyntaxError: Cannot use import statement outside a module. npm init -y --init-type=module schreibt gleich "module" hinein.

Die Felder, die wirklich etwas tun

Eine package.json, die etwas bewirkt
import { readFile } from "node:fs/promises";

const eintraege = JSON.parse(await readFile("daten.json", "utf8"));

console.log(`${eintraege.length} Einträge geladen`);

Ein vollständiges kleines Projekt, mit einer Beschreibung, einer Datenliste und einem Programm, das sie liest. Gestartet schreibt es 4 Einträge geladen ins Terminal. Wichtiger als die vier Einträge sind aber die Felder daneben.

type ist der wichtigste Eintrag für diesen Kurs. Steht dort "module", behandelt Node jede .js-Datei im Projekt als ES-Modul. Das ist der Schalter aus Lektion 2.2. Ab diesem Abschnitt steht er in jedem Projekt des Kurses, und die Dateien heißen deshalb .js statt .mjs.

main sagt, welche Datei gemeint ist, wenn jemand dein Paket einbindet, ohne eine Datei zu nennen. Auch node . startet im Projektordner genau diese Datei.

scripts ist der zweite wichtige Eintrag. Darin stehen Befehle, jeder unter einem eigenen Namen.

In dependencies und devDependencies stehen die Pakete, die dein Projekt braucht, seine Abhängigkeiten (englisch dependencies). Von Hand schreibt man sie meistens nicht, und genauer geht es in der nächsten Lektion darum.

engines hält fest, mit welchen Node-Versionen dein Projekt laufen soll. Passt es nicht, warnt npm. Manche Hosting-Anbieter lesen das Feld auch und richten sich danach.

private ist ein Wächter. Steht dort true, weigert sich npm publish, das Projekt zu veröffentlichen. Das klingt nach einem Detail, bis es jemandem zum ersten Mal passiert. Ich trage "private": true in jedes Projekt ein, das nicht veröffentlicht werden soll, und das sind fast alle.

name, version, description, author, license und keywords sind dagegen reine Beschreibung. Wichtig werden sie erst, wenn du wirklich veröffentlichst.

Warum scripts mehr ist als eine Abkürzung

Was npm bei npm start tut, siehst du mit demselben Befehl aus der Befehlsleiste des ersten Beispiels. Im Terminal stehen danach erst > einkaufsliste@1.0.0 start und > node index.js. Das sind Projekt, Version und der Befehl, den npm gleich ausführt, und darunter kommt die Ausgabe des Programms.

npm start und npm test sind eine Verabredung, die in jedem Node-Projekt der Welt gleich heißt. Wer dein Projekt zum ersten Mal in die Hand nimmt, probiert diese beiden. Funktionieren sie, ist er drin. In der README muss er dann nicht erst nachlesen, ob das Ding nun mit node server.js, node src/main.js oder node --env-file=.env app.js startet.

Dasselbe gilt für Werkzeuge. Ein Hosting-Anbieter, der dein Projekt auf seinen Server bringt (das heißt Deployment), ruft npm start auf. Eine CI-Pipeline ruft npm test auf. Beide fragen nicht nach.

Ein eigener Befehl mit npm run
import { readFile } from "node:fs/promises";

const eintraege = JSON.parse(await readFile("daten.json", "utf8"));
const buchstaben = eintraege.reduce((summe, eintrag) => summe + eintrag.length, 0);

console.log(`${eintraege.length} Einträge, ${buchstaben} Buchstaben`);

Eigene Namen gehen auch, dann aber mit npm run davor. start und test gehen ohne das run, ebenso wie die selteneren stop und restart. Fehlt das run vor einem eigenen Namen, antwortet npm mit Unknown command: "zaehlen" und schlägt im selben Atemzug npm run zaehlen vor.

Was in scripts steht, ist außerdem dokumentiert. Der lange Befehl mit den drei Optionen steht an einer Stelle und nicht in der Bash-Historie von drei verschiedenen Leuten.

Was passiert, wenn type fehlt

Früher brach ein import in einer .js-Datei ohne "type": "module" mit SyntaxError: Cannot use import statement outside a module ab.

Seit Node 22.7 ist Node nachsichtiger. Es versucht die Datei erst als CommonJS zu lesen und merkt am import, dass das nicht aufgeht. Dann liest es sie noch einmal als ES-Modul.

Eine package.json ohne type
import { readFile } from "node:fs/promises";

const eintraege = JSON.parse(await readFile("daten.json", "utf8"));

console.log(`${eintraege.length} Einträge geladen`);

Das Programm läuft und meldet seine vier Einträge, schreibt aber eine Warnung auf den Fehlerkanal. Nach der Nummer des Prozesses steht in eckigen Klammern ihr Code, [MODULE_TYPELESS_PACKAGE_JSON], und danach, dass der Typ des Moduls nicht angegeben ist und sich die Datei nicht als CommonJS lesen lässt (doesn't parse as CommonJS). Die zweite Zeile sagt, dass das zweite Lesen Zeit kostet, und die dritte nennt den Ausweg, add "type": "module" in die package.json.

Der Eintrag "type" gehört trotzdem hinein, auch wenn nichts abstürzt. Ohne ihn muss Node bei jedem Start raten, was gemeint ist. In einem Projekt mit vielen Dateien ist das nicht mehr nur ein Schönheitsfehler.

Die Datei ist auch ein Sicherheitsthema

Wird das Projekt veröffentlicht, ist alles öffentlich, was in der package.json steht, auch die Mailadresse im Feld author.

Zugangsdaten haben hier also nichts verloren, auch nicht in einem scripts-Eintrag. Dafür gibt es die .env aus Lektion 4.2, und die steht in der .gitignore.

In der Aufgabe wird das Werkzeug aus Abschnitt 4 zu einem Projekt mit einer eigenen package.json.

Zum Mitnehmen

Die package.json beschreibt ein Projekt. type macht aus .js-Dateien ES-Module, scripts legt fest, was npm start ausführt, und private verhindert eine Veröffentlichung aus Versehen.

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 3 Beispielen zum Ausprobieren

    Steht hier, ohne Konto lesbar.

  • Aufgabe, auf dem Server geprüft

    Öffnet sich mit dem Basis Konto.