So erstellst du eine package.json für Node.js

Die package.json-Datei ist das Herzstück jedes Node.js-Projekts. Sie fungiert als Manifest, das Abhängigkeiten auflistet, Automatisierungsskripte definiert und das Verhalten des Projekts konfiguriert. Dieser Leitfaden zeigt, wie du eine robuste package.json konfigurierst und dabei sicherstellst, dass dein Projekt reproduzierbar, organisiert und mit der Square-Cloud-Umgebung kompatibel ist.

Das Projekt initialisieren

Der sicherste Weg, die Datei zu erstellen, ist die Verwendung der NPM CLI. Navigiere zum Stammverzeichnis deines Projekts und wähle eine der Optionen:Option A: Interaktiv (empfohlen für Einsteiger) Beantworte die Fragen Schritt für Schritt, um benutzerdefinierte Metadaten zu konfigurieren.

npm init

Option B: Automatisch (Standard) Erzeugt die Datei sofort und übernimmt alle Standardeinstellungen.

npm init -y

Wesentliche Metadaten konfigurieren

Öffne die erzeugte package.json. Für ein professionelles Projekt stelle sicher, dass diese Felder korrekt ausgefüllt sind:

name: Eindeutiger Projektbezeichner (verwende kebab-case, z. B. my-project-api).
version: Folgt dem SemVer-Standard (z. B. 1.0.0).
main: Der Einstiegspunkt der Anwendung (üblicherweise index.js oder src/index.js).
type: Setze auf "module", wenn du ES Modules (import/export) verwendest, oder entferne es, um CommonJS (require) zu verwenden.

Ausführungsskripte konfigurieren

Der Abschnitt scripts ist entscheidend für die Automatisierung. Hier definierst du, wie deine Anwendung gestartet, getestet oder gebaut werden soll.

"scripts": {
  "start": "node index.js",
  "test": "echo \"Error: no test specified\" && exit 1"
}

Zur Initialisierung auf Square Cloud: Standardmäßig führt Square Cloud node MAIN aus (die in MAIN festgelegte Datei), bietet aber volle Flexibilität. Du kannst (und solltest) explizit konfigurieren, welchen Befehl das System zum Starten deiner Anwendung ausführen soll.Zum Beispiel kannst du den Start Command im Dashboard oder in der Square-Konfigurationsdatei so konfigurieren, dass npm run start ausgeführt wird, wodurch sichergestellt wird, dass das oben definierte Skript respektiert wird.

Abhängigkeiten verwalten

Hier liegen die essenziellen Bibliotheken, damit dein Code in der Produktion läuft. Um zu installieren und automatisch zu dieser Liste hinzuzufügen:

npm install package-name

Achtung bei devDependencies und Build auf Square Cloud: Werkzeuge, die nur in der lokalen Entwicklung verwendet werden (wie eslint oder prettier), verbleiben in devDependencies.

Wichtig: Square Cloud führt die Installation standardmäßig im Produktionsmodus durch, was bedeutet, dass die in devDependencies aufgeführten Pakete NICHT installiert werden.Wenn du einen Build-Prozess in der Cloud ausführen musst (z. B. TypeScript kompilieren oder Post-Install-Skripte ausführen), musst du diese Werkzeuge nach dependencies verschieben. Andernfalls schlägt der Build wegen fehlender Pakete fehl.

Erweiterte Funktionen nutzen

Für komplexere Projekte bietet package.json leistungsstarke Steuerungsfunktionen:1. Overrides (Versionen erzwingen): Nützlich, wenn eine von dir verwendete Abhängigkeit eine Unterabhängigkeit mit mehreren Sicherheitslücken installiert. Du kannst die Auflösung auf eine sichere Version erzwingen:

"overrides": {
  "vulnerable-package": "2.0.1"
}

2. Imports (Pfad-Aliase): Vermeide lange relative Pfade wie ../../../utils. Mit imports erstellst du native interne Abkürzungen (erfordert ein aktuelles Node):

"imports": {
  "#utils/*": "./src/utils/*.js",
  "#database": "./src/core/database.js"
}

Dies ermöglicht den Import im Code mittels import db from '#database'.

Tipps und Best Practices

Semantische Versionierung: Ziehe es vor, kritische Versionen festzupinnen, indem du ^ entfernst (verwende z. B. "14.14.1" statt "^14.14.1"), um zu verhindern, dass automatische Updates deinen Produktionscode brechen.
Sicherheit: Führe regelmäßig npm audit aus, um Sicherheitslücken in deinen Abhängigkeiten zu erkennen. Das oben erläuterte Feld overrides ist die ideale Lösung, um diese Probleme zu beheben.
package-lock.json: Behalte sie in Git: Sie hält genau den Abhängigkeitsbaum fest, der auf deiner Maschine funktioniert hat. Die Square Cloud CLI und die VS Code-Erweiterung lassen Lock-Dateien standardmäßig beim Upload weg, daher installiert Square Cloud die neuesten Versionen, die die Bereiche in package.json erlauben. Brauchst du die festgehaltenen Versionen, nimm sie mit !package-lock.json in deiner squarecloud.ignore wieder auf.
Organisation: Halte die Datei sauber. Wenn der Abschnitt scripts zu groß wird, ziehe die Verwendung externer Automatisierungswerkzeuge oder eine Aufteilung in mehrere Dateien in Betracht.

Abschließendes Dateibeispiel

Nachfolgend ein Beispiel für eine moderne und optimierte package.json:

package.json

{
  "name": "square-cloud-project",
  "version": "1.0.0",
  "description": "Professional Node.js API",
  "main": "src/index.js",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "lint": "eslint ."
  },
  "imports": {
    "#services/*": "./src/services/*.js"
  },
  "dependencies": {
    "discord.js": "14.14.1",
    "dotenv": "16.3.1",
    "typescript": "5.3.3" 
  },
  "devDependencies": {
    "eslint": "8.56.0"
  }
}

Nächste Schritte

Sobald deine package.json-Datei konfiguriert ist:

Committe sie in dein Git-Repository.
Hoste dein Projekt mit dem Leitfaden zur Node.js-Runtime oder folge einem Framework-Leitfaden wie Express oder Next.js.
Automatisch aus GitHub deployen, bei jedem Push.

Dienste

Fehlerbehebung

Runtimes

Plattform

Changelog

So erstellst du eine package.json für Node.js

Tipps und Best Practices

Abschließendes Dateibeispiel

Nächste Schritte

​Tipps und Best Practices

​Abschließendes Dateibeispiel

​Nächste Schritte

Tipps und Best Practices

Abschließendes Dateibeispiel

Nächste Schritte