Wissensdatenbank

Diese Anleitung erklärt, wie Sie eine moderne Next.js Applikation (React Framework) über NGINX Unit in DirectAdmin (https://cp.jstrauss.at) deployen. Da Next.js standardmäßig einen eigenen Server-Prozess benötigt, nutzen wir den "Standalone"-Modus, um die App kompatibel und performant zu betreiben.

Voraussetzungen

• Eine funktionierende Next.js Applikation (lokal).

• Zugang zum DirectAdmin Panel.

• NGINX Unit Unterstützung aktiviert. (Ab Plus Paket)

Schritt 1: Next.js Konfiguration anpassen

Damit die Applikation ohne riesige node_modules auf dem Server läuft, muss der Standalone-Mode aktiviert werden.

Öffnen Sie lokal Ihre next.config.mjs (oder .js) und fügen Sie output: "standalone" hinzu:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
  // weitere Konfigurationen...
};

export default nextConfig;

Schritt 2: Build erstellen und Dateien vorbereiten

Führen Sie lokal den Build-Befehl aus:

npm run build

Wichtig: Next.js erstellt im Standalone-Modus nicht automatisch alle statischen Ressourcen im Zielordner. Diese müssen manuell zusammengeführt werden.

1. Navigieren Sie in Ihrem Projekt zu .next/standalone. Dies ist Ihr Basis-Upload-Ordner.

2. Kopieren Sie den Ordner public aus Ihrem Hauptverzeichnis nach .next/standalone/public.

3. Kopieren Sie den Ordner .next/static aus Ihrem Hauptverzeichnis nach .next/standalone/.next/static.

Die Ordnerstruktur für den Upload muss am Ende so aussehen:

• ???? ihre-app/ (Basisordner)

  • ???? package.json

  • ???? server.js

  • ???? public/ (Bilder, Favicons etc.)

  • ???? .next/

    • ???? server/

    • ???? static/ (CSS, JS Chunks, Media)

Schritt 3: Den NGINX Unit Wrapper erstellen (run.js)

Aktuelle Versionen von Next.js und NGINX Unit haben teilweise Kompatibilitätsprobleme (speziell beim Header-Handling). Um "500er Fehler" zu vermeiden, erstellen Sie eine Datei namens run.js im selben Ordner wie die server.js.

Inhalt der run.js:

const http = require('http');

// NGINX Unit Polyfill: Fix für fehlende appendHeader Funktion
if (!http.ServerResponse.prototype.appendHeader) {
  http.ServerResponse.prototype.appendHeader = function (name, value) {
    const existing = this.getHeader(name);
    if (!existing) {
      return this.setHeader(name, value);
    }
    if (Array.isArray(existing)) {
      return this.setHeader(name, [...existing, value]);
    }
    return this.setHeader(name, [existing, value]);
  };
}

// Startet den eigentlichen Next.js Server
require('./server.js');

Schritt 4: Upload auf den Server

Laden Sie nun den gesamten Inhalt des Ordners (inklusive .next, public, server.js und run.js) auf Ihren Server hoch (z.B. per FTP oder Dateimanager).

• Zielbeispiel: /home/user/domains/ihredomain.de/next-app/

Schritt 5: NGINX Unit Applikation erstellen

Gehen Sie in DirectAdmin zu NGINX Unit und klicken Sie auf "Neue Applikation erstellen".

• Name: NextApp (oder eigener Name)

• Typ: Node.js

• Arbeitsverzeichnis: Wählen Sie den Pfad, in den Sie eben hochgeladen haben (z.B. .../next-app/).

• Skript: run.js (Wählen Sie hier unser Wrapper-Skript, nicht die server.js!)

• Argumente: Leer lassen.

Klicken Sie auf Erstellen.

Schritt 6: Route konfigurieren

Nach dem Erstellen der App müssen Sie eine Route definieren, damit die App erreichbar ist.

1. Klicken Sie auf Route erstellen.

2. Standort: / (Damit alle Unterseiten funktionieren).

3. Applikation: Wählen Sie die eben erstellte NextApp.

4. Pfad statischer Inhalte: Lassen Sie dieses Feld LEER!

   • Hinweis: Next.js liefert statische Dateien (CSS/Bilder) selbst aus. Wenn Sie hier einen Pfad setzen, kann dies zu 404-Fehlern führen.

Klicken Sie auf Erstellen. Ihre App sollte nun unter Ihrer Domain erreichbar sein.

Fehlerbehebung (Troubleshooting)

CSS oder Bilder werden nicht geladen (404 Fehler)? Überprüfen Sie Schritt 2. Oft wurde vergessen, den Ordner .next/static manuell auf den Server hochzuladen. Der Ordner muss auf dem Server unter .next/static existieren.

Server Fehler 500 beim Start? Stellen Sie sicher, dass Sie als Start-Skript die run.js und nicht die server.js ausgewählt haben.