Zum Hauptinhalt springen

​
📋 package.json-Datei 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.
1

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
2

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.
3

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: Obwohl die Umgebung nach gängigen Mustern sucht, bietet Square Cloud 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.
4

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.
5

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: Lösche oder ignoriere diese Datei niemals in .gitignore. Sie ist die Garantie dafür, dass Square Cloud genau den Abhängigkeitsbaum installiert, der auf deiner Maschine funktioniert hat.
  • 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:
  1. Committe sie in dein Git-Repository.
  2. Hoste dein Projekt auf Square Cloud.
  3. Konfiguriere den automatischen Deploy über GitHub.
  4. Willkommen beim professionellen Hosting von Node.js-Anwendungen!
Eine gut strukturierte package.json-Datei ist die Grundlage für jede erfolgreiche Node.js-Anwendung und stellt sicher, dass deine Anwendung auf Square Cloud einwandfrei funktioniert.