Frameworks supportés

Frameworks supportés

À chaque déploiement depuis GitHub, le builder clone votre branche et analyse le dépôt pour identifier le framework : il en déduit la commande de build, les artefacts à embarquer dans l'image de production et la commande de démarrage adaptée. Le framework retenu et la commande générée s'affichent dans les logs de build, à l'étape « Détection du framework ».

Cette page est la référence complète : signaux de détection, commandes générées, notes par framework et méthodes de surcharge.

Comment fonctionne la détection

La détection suit un ordre strict, du plus spécifique au plus générique :

1. Le mode Dockerfile, s'il est choisi dans les réglages du service : votre Dockerfile fait foi et aucune détection n'est appliquée (voir Surcharger la détection).
2. Meta-frameworks (Next.js, Nuxt, SvelteKit, Remix, Astro…), détectés avant leurs briques : un projet Blitz n'est pas confondu avec le Next.js qu'il embarque, un projet Qwik ou Vike n'est pas réduit à sa config Vite.
3. Frameworks Python (Django, FastAPI, Flask) et pipelines statiques (Gulp).
4. Frameworks backend Node.js (NestJS, Fastify, Koa…). Express est testé en dernier, car il apparaît en dépendance directe de beaucoup d'autres frameworks.
5. Génériques par langage : Node.js avec script start, Laravel, Go, Ruby on Rails, Rust.

Deux types de signaux sont utilisés, dans cet ordre de confiance :

• Les dépendances de package.json (dependencies + devDependencies). Le signal le plus fiable : beaucoup de frameworks fonctionnent sans fichier de config.
• Les fichiers conventionnels : next.config.*, astro.config.*, go.mod, Cargo.toml, manage.py, artisan…

Résolution de la commande de démarrage (Node.js)

Pour les frameworks Node « bruts » (Express, Koa, Fastify…), la commande de démarrage se résout par ordre de préférence :

1. Le script start de votre package.json → npm start. Vous savez mieux que nous comment démarrer votre application.
2. Le champ main s'il pointe vers un fichier existant → node <main>.
3. Les points d'entrée conventionnels du framework présents dans le dépôt (ex. app.js pour Koa, server.js pour Fastify).
4. La sortie de build attendue en dernier recours (ex. dist/main.js pour NestJS : le fichier n'existe pas au clone mais sera produit par le build).

Les frameworks compilés (NestJS, AdonisJS, FoalTS, Marble.js) démarrent directement sur leur sortie de build plutôt que sur leur CLI de développement : boot plus rapide, pas d'outillage de dev requis dans l'image.

Fullstack & SSR

Notes par framework

• Next.js : le mode standalone est détecté automatiquement (output: 'standalone' dans next.config.*) : l'image finale n'embarque que .next/standalone, .next/static et public. Voir aussi le guide Next.js.
• Nuxt / SolidStart : les deux produisent une sortie Nitro, et seul le dossier .output est gardé dans l'image finale.
• SvelteKit : la commande générée suppose adapter-node (@sveltejs/adapter-node), qui produit build/index.js. Les adapters serverless (Vercel, Netlify…) ne produisent pas de serveur autonome.
• Remix : les deux ères sont gérées : compilateur classique (remix.config.* présent) et plugin Vite (dépendance @remix-run/* seule).
• Astro : SSR si un adapter figure dans astro.config.* (utilisez @astrojs/node), sinon le site est servi statiquement depuis dist/.
• Qwik City : lancez npx qwik add express pour le SSR. La présence de src/entry.express.tsx déclenche le mode serveur ; sinon la sortie dist/ est servie statiquement.
• RedwoodJS : build et serve passent par la CLI rw, qui gère le monorepo api + web.
• Vike : Vike suppose un serveur custom. Définissez un script start dans votre package.json ; à défaut, le builder cherche server/index.js, server.js puis index.js.
• Fresh / Deno : runtime différent. Le builder auto utilise l'image Deno officielle : il lance la tâche start de votre deno.json si elle existe, sinon le premier fichier d'entrée trouvé (main.ts, server.ts…).

Backend Node.js

La notation npm start › main › fichiers… désigne l'ordre de résolution décrit plus haut.

Notes par framework

• NestJS : nest start recompile au boot et exige la CLI Nest. Le builder lance directement dist/main.js, produit par npm run build (nest build). Vérifiez que votre script build existe.
• AdonisJS : la version est déduite de la présence d'adonisrc.ts (v6). Les chemins de sortie diffèrent entre v5 et v6.
• Egg.js : egg-scripts tourne en avant-plan (pas de --daemon). Dans un conteneur, le process principal est l'application.
• Moleculer : sans script start, le runner charge les services depuis le dossier services/.
• LoopBack 4 : node . suit le champ main (généralement dist/index.js, produit par le build TypeScript).

Frontend statique

Pour Gulp, le dossier de sortie est extrait du premier appel dest() du gulpfile ; à défaut, dist/, www/ puis build/ sont essayés. Seul le dossier de sortie est embarqué dans l'image finale.

La nature « Site statique »

Le tableau ci-dessus décrit la détection automatique, qui suppose un projet Node. Quand vous choisissez la nature Site statique à la création du service (ou depuis ses Paramètres), le build ne passe plus par la détection automatique : l'image produite est un Nginx qui sert vos fichiers.

• Dépôt de fichiers HTML/CSS/JS : le dossier contenant index.html est publié tel quel (racine, puis public, dist, build, site, _site, www).
• Dépôt avec un script build : il est exécuté, et seule sa sortie est embarquée (dist, build, out, _site, .output/public, public, www).
• Nginx écoute sur le port du service, sert les URL sans extension (/a-propos → a-propos.html) et retombe sur index.html pour les routeurs côté client.
• Aucun dépôt sous la main ? Le template Site statique déploie le même Nginx avec un dossier persistant, éditable depuis l'onglet Fichiers.

Autres runtimes

Les guides dédiés Python, PHP et Go détaillent les variables d'environnement propres à chaque runtime.

Le port : la seule convention exigée

Quel que soit le framework, votre application doit lire la variable d'environnement PORT et écouter sur 0.0.0.0, et non sur localhost ni sur un port codé en dur. C'est la cause n°1 des déploiements qui buildent mais ne répondent pas.

// Node.js — valable pour tous les frameworks
const port = process.env.PORT || 3000;
app.listen(port, "0.0.0.0");

Surcharger la détection

Trois mécanismes, du plus léger au plus complet :

1. Commande de démarrage personnalisée

Depuis le dashboard, remplacez la commande générée sans toucher au dépôt (voir Commande de démarrage personnalisée).

2. Procfile

Une ligne web: <commande> dans un Procfile à la racine de votre dépôt remplace la commande de démarrage détectée. Elle vaut pour tous les langages, sauf les projets Node, qui passent par la commande de démarrage du dashboard.

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

3. Mode Dockerfile

Dans les réglages du service, changez le type de build :

• Dockerfile : votre dépôt pilote entièrement le build, sans détection et selon vos règles (voir Docker).

Gestionnaire de paquets

Le builder normalise tout projet Node sur npm au moment du build : c'est le seul gestionnaire garanti présent dans toutes les images de base. Dans la copie clonée du dépôt :

• les lockfiles bun.lock, bun.lockb, pnpm-lock.yaml, yarn.lock et package-lock.json sont supprimés : les dépendances sont réinstallées proprement via npm install ;
• le champ packageManager (corepack) et les entrées engines.pnpm / engines.yarn / engines.bun sont retirés du package.json ;
• les configs propres à un autre gestionnaire (pnpm-workspace.yaml, .yarnrc.yml, .yarn/, bunfig.toml…) sont supprimées ;
• les scripts qui appellent un autre gestionnaire sont réécrits (pnpm run build → npm run build, bunx prisma → npx prisma, yarn dlx → npx…), et la garde only-allow, dont le rôle est de faire échouer npm install, est retirée.

Votre dépôt reste inchangé : seule la copie utilisée pour construire l'image est modifiée. Un lockfile désynchronisé ne peut donc jamais faire échouer un déploiement.

Ce qui n'a pas d'équivalent npm (pnpm --filter, yarn workspace, bun run app.ts) est laissé tel quel et signalé dans les logs de build, à l'étape « Gestionnaire de paquets ». Ces commandes échoueront : adaptez le script dans votre dépôt, ou passez en mode Dockerfile pour piloter vous-même l'installation.

Dépannage

• Mauvais framework détecté : vérifiez les logs de build (étape « Détection du framework »). Le cas typique est une dépendance résiduelle dans package.json (ex. express dans un projet migré). Nettoyez la dépendance ou passez en mode Dockerfile.
• Build OK mais le service ne répond pas : presque toujours le port. Vérifiez aussi que votre commande de démarrage n'écoute pas en localhost.
• Cannot find module 'dist/main.js' au boot d'un framework compilé : votre script build ne produit pas la sortie attendue. Alignez la sortie de build ou définissez un script start.
• Framework absent de cette liste : Le builder auto tente une détection générique par langage. Si elle échoue, ajoutez un Procfile ou passez en mode Dockerfile, et dites-nous quel framework vous manque sur le Discord (leiho berria).