> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# So erstellst du deine package.json-Datei

> Vollständiger Leitfaden zur package.json-Datei in Node.js: Lerne, wie du sie erstellst, Skripte konfigurierst, Abhängigkeiten verwaltest und dein Projekt für den Produktions-Deploy vorbereitest.

# 📋 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.

***

<Steps>
  <Step title="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.

    ```bash theme={null}
    npm init
    ```

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

    ```bash theme={null}
    npm init -y
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Ausführungsskripte konfigurieren">
    Der Abschnitt `scripts` ist entscheidend für die Automatisierung. Hier definierst du, wie deine Anwendung gestartet, getestet oder gebaut werden soll.

    ```json theme={null}
    "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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    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`.

    <Warning>
      **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.
    </Warning>
  </Step>

  <Step title="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:

    ```json theme={null}
    "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):

    ```json theme={null}
    "imports": {
      "#utils/*": "./src/utils/*.js",
      "#database": "./src/core/database.js"
    }
    ```

    Dies ermöglicht den Import im Code mittels `import db from '#database'`.
  </Step>
</Steps>

***

## 💡 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`:

```json package.json theme={null}
{
  "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.