Unterstützte Frameworks

Unterstützte Frameworks

Bei jedem Deployment von GitHub klont der Builder Ihren Branch und analysiert das Repository, um das Framework zu identifizieren: daraus leitet er den Build-Befehl, die in das Produktions-Image einzubindenden Artefakte und den passenden Startbefehl ab. Das gewählte Framework und der generierte Befehl werden in den Build-Logs beim Schritt „Framework-Erkennung" angezeigt.

Diese Seite ist die vollständige Referenz: Erkennungssignale, generierte Befehle, Hinweise je Framework und Methoden zum Überschreiben.

Wie die Erkennung funktioniert

Die Erkennung folgt einer strikten Reihenfolge, vom spezifischsten zum allgemeinsten:

1. Der Dockerfile-Modus, wenn er in den Einstellungen des Dienstes gewählt ist: Ihr Dockerfile ist maßgeblich, und keine Erkennung wird angewendet (siehe Erkennung überschreiben).
2. Meta-Frameworks (Next.js, Nuxt, SvelteKit, Remix, Astro…), erkannt vor ihren Bausteinen: ein Blitz-Projekt wird nicht mit dem darin enthaltenen Next.js verwechselt, ein Qwik- oder Vike-Projekt wird nicht auf seine Vite-Konfiguration reduziert.
3. Python-Frameworks (Django, FastAPI, Flask) und statische Pipelines (Gulp).
4. Node.js-Backend-Frameworks (NestJS, Fastify, Koa…). Express wird zuletzt geprüft, da es als direkte Abhängigkeit vieler anderer Frameworks erscheint.
5. Generisch nach Sprache: Node.js mit start-Skript, Laravel, Go, Ruby on Rails, Rust.

Zwei Arten von Signalen werden verwendet, in dieser Vertrauensreihenfolge:

• Die Abhängigkeiten von package.json (dependencies + devDependencies). Das zuverlässigste Signal: viele Frameworks funktionieren ohne Konfigurationsdatei.
• Konventionelle Dateien: next.config.*, astro.config.*, go.mod, Cargo.toml, manage.py, artisan…

Auflösung des Startbefehls (Node.js)

Für „rohe" Node-Frameworks (Express, Koa, Fastify…) wird der Startbefehl in dieser Präferenzreihenfolge aufgelöst:

1. Das start-Skript Ihrer package.json → npm start. Sie wissen besser als wir, wie Ihre Anwendung zu starten ist.
2. Das Feld main, wenn es auf eine vorhandene Datei zeigt → node <main>.
3. Die konventionellen Einstiegspunkte des Frameworks, die im Repository vorhanden sind (z. B. app.js für Koa, server.js für Fastify).
4. Die erwartete Build-Ausgabe als letztes Mittel (z. B. dist/main.js für NestJS: die Datei existiert beim Klonen nicht, wird aber vom Build erzeugt).

Kompilierte Frameworks (NestJS, AdonisJS, FoalTS, Marble.js) starten direkt von ihrer Build-Ausgabe statt von ihrer Entwicklungs-CLI: schnellerer Boot, kein Dev-Tooling im Image erforderlich.

Fullstack & SSR

Hinweise je Framework

• Next.js: der Standalone-Modus wird automatisch erkannt (output: 'standalone' in next.config.*): das finale Image enthält nur .next/standalone, .next/static und public. Siehe auch die Anleitung Next.js.
• Nuxt / SolidStart: beide erzeugen eine Nitro-Ausgabe, und nur der Ordner .output wird im finalen Image behalten.
• SvelteKit: der generierte Befehl setzt adapter-node voraus (@sveltejs/adapter-node), der build/index.js erzeugt. Serverless-Adapter (Vercel, Netlify…) erzeugen keinen eigenständigen Server.
• Remix: beide Ären werden unterstützt: klassischer Compiler (remix.config.* vorhanden) und Vite-Plugin (nur @remix-run/*-Abhängigkeit).
• Astro: SSR, wenn ein adapter in astro.config.* erscheint (verwenden Sie @astrojs/node), sonst wird die Seite statisch aus dist/ bereitgestellt.
• Qwik City: führen Sie npx qwik add express für SSR aus. Das Vorhandensein von src/entry.express.tsx löst den Server-Modus aus; sonst wird die dist/-Ausgabe statisch bereitgestellt.
• RedwoodJS: Build und Serve laufen über die rw-CLI, die das api + web Monorepo verwaltet.
• Vike: Vike setzt einen benutzerdefinierten Server voraus. Definieren Sie ein start-Skript in Ihrer package.json; andernfalls sucht der Builder nach server/index.js, server.js und dann index.js.
• Fresh / Deno: andere Runtime. Der Auto-Builder verwendet das offizielle Deno-Image: Er startet den Task start aus Ihrer deno.json, falls vorhanden, sonst die erste gefundene Einstiegsdatei (main.ts, server.ts…).

Node.js-Backend

Die Notation npm start › main › Dateien… bezeichnet die oben beschriebene Auflösungsreihenfolge.

Hinweise je Framework

• NestJS: nest start kompiliert beim Boot neu und erfordert die Nest-CLI. Der Builder startet direkt dist/main.js, erzeugt von npm run build (nest build). Prüfen Sie, ob Ihr build-Skript existiert.
• AdonisJS: die Version wird aus dem Vorhandensein von adonisrc.ts (v6) abgeleitet. Die Ausgabepfade unterscheiden sich zwischen v5 und v6.
• Egg.js: egg-scripts läuft im Vordergrund (kein --daemon). In einem Container ist der Hauptprozess die Anwendung.
• Moleculer: ohne start-Skript lädt der Runner die Dienste aus dem Ordner services/.
• LoopBack 4: node . folgt dem Feld main (normalerweise dist/index.js, erzeugt vom TypeScript-Build).

Statisches Frontend

Für Gulp wird der Ausgabeordner aus dem ersten dest()-Aufruf des Gulpfiles extrahiert; andernfalls werden dist/, www/ und dann build/ versucht. Nur der Ausgabeordner wird im finalen Image eingebettet.

Die Art »Statische Website«

Die Tabelle oben beschreibt die automatische Erkennung, die ein Node-Projekt voraussetzt. Wenn Sie beim Anlegen des Dienstes (oder später in dessen Einstellungen) die Art Statische Website wählen, läuft der Build gar nicht mehr über die automatische Erkennung: Das erzeugte Image ist ein Nginx, das Ihre Dateien ausliefert.

• Repository aus HTML/CSS/JS-Dateien: Der Ordner mit index.html wird unverändert veröffentlicht (Wurzel, dann public, dist, build, site, _site, www).
• Repository mit build-Skript: Es wird ausgeführt, und nur dessen Ausgabe landet im Image (dist, build, out, _site, .output/public, public, www).
• Nginx lauscht auf dem Port des Dienstes, liefert URLs ohne Endung (/ueber-uns → ueber-uns.html) und fällt für clientseitige Router auf index.html zurück.
• Kein Repository zur Hand? Die Vorlage Statische Website deployt dasselbe Nginx mit einem persistenten Ordner, bearbeitbar über den Tab Dateien.

Andere Runtimes

Die dedizierten Anleitungen Python, PHP und Go beschreiben im Detail die runtime-spezifischen Umgebungsvariablen.

Der Port: die einzig erforderliche Konvention

Unabhängig vom Framework muss Ihre Anwendung die Umgebungsvariable PORT lesen und auf 0.0.0.0 lauschen, niemals auf localhost oder einem fest codierten Port. Das ist die häufigste Ursache Nr. 1 für Deployments, die bauen, aber nicht antworten.

// Node.js — gültig für alle Frameworks
const port = process.env.PORT || 3000;
app.listen(port, "0.0.0.0");

Erkennung überschreiben

Drei Mechanismen, vom leichtesten zum vollständigsten:

1. Benutzerdefinierter Startbefehl

Ersetzen Sie vom Dashboard aus den generierten Befehl, ohne das Repository anzufassen (siehe Benutzerdefinierter Startbefehl).

2. Procfile

Eine Zeile web: <Befehl> in einem Procfile im Wurzelverzeichnis Ihres Repositories ersetzt den erkannten Startbefehl. Sie gilt für alle Sprachen außer Node-Projekten, die stattdessen den Startbefehl aus dem Dashboard verwenden.

web: gunicorn meineapp.wsgi --bind 0.0.0.0:$PORT

3. Dockerfile-Modus

Ändern Sie in den Einstellungen des Dienstes den Build-Typ:

• Dockerfile: Ihr Repository steuert den Build vollständig, ohne Erkennung und nach Ihren Regeln (siehe Docker).

Paketmanager

Der Builder normalisiert jedes Node-Projekt auf npm zum Build-Zeitpunkt: npm ist der einzige Paketmanager, der in allen Basis-Images garantiert vorhanden ist. In der geklonten Kopie des Repositories gilt:

• die Lockfiles bun.lock, bun.lockb, pnpm-lock.yaml, yarn.lock und package-lock.json werden gelöscht: die Abhängigkeiten werden sauber über npm install neu installiert;
• das Feld packageManager (corepack) sowie die Einträge engines.pnpm / engines.yarn / engines.bun werden aus der package.json entfernt;
• Konfigurationsdateien anderer Paketmanager (pnpm-workspace.yaml, .yarnrc.yml, .yarn/, bunfig.toml…) werden gelöscht;
• Skripte, die einen anderen Paketmanager aufrufen, werden umgeschrieben (pnpm run build → npm run build, bunx prisma → npx prisma, yarn dlx → npx…), und die only-allow-Sperre, deren einziger Zweck es ist, npm install scheitern zu lassen, wird entfernt.

Ihr Repository bleibt unverändert: nur die zum Bauen des Images verwendete Kopie wird angepasst. Ein desynchronisiertes Lockfile kann daher niemals ein Deployment zum Scheitern bringen.

Was kein npm-Äquivalent hat (pnpm --filter, yarn workspace, bun run app.ts), bleibt unangetastet und wird in den Build-Logs im Schritt „Paketmanager" gemeldet. Diese Befehle werden fehlschlagen: passen Sie das Skript im Repository an oder wechseln Sie in den Dockerfile-Modus, um die Installation selbst zu steuern.

Fehlerbehebung

• Falsches Framework erkannt: prüfen Sie die Build-Logs (Schritt „Framework-Erkennung"). Der typische Fall ist eine übrig gebliebene Abhängigkeit in package.json (z. B. express in einem migrierten Projekt). Entfernen Sie die Abhängigkeit oder wechseln Sie in den Dockerfile-Modus.
• Build OK, aber der Dienst antwortet nicht: fast immer der Port. Prüfen Sie auch, dass Ihr Startbefehl nicht auf localhost lauscht.
• Cannot find module 'dist/main.js' beim Boot eines kompilierten Frameworks: Ihr build-Skript erzeugt nicht die erwartete Ausgabe. Richten Sie die Build-Ausgabe aus oder definieren Sie ein start-Skript.
• Framework fehlt in dieser Liste: Der Auto-Builder versucht eine generische Erkennung nach Sprache. Wenn das fehlschlägt, fügen Sie ein Procfile hinzu oder wechseln Sie in den Dockerfile-Modus, und teilen Sie uns mit, welches Framework Ihnen fehlt, auf Discord (neues Fenster).