Configuration de votre commande de compilation et de votre répertoire de sortie

Getting Orbit to build your project correctly comes down to a handful of fields in Settings: install command, build command, output directory, root directory and Node.js version. Left blank they are…

Configurer votre commande de build et répertoire de sortie

Pour que Orbit construise correctement votre projet, tout dépend d'une poignée de champs dans Paramètres : commande d'installation, commande de build, répertoire de sortie, répertoire racine et version Node.js. S'ils sont laissés vides, ils sont détectés automatiquement, et la plupart des problèmes de premier déploiement proviennent d'une valeur détectée automatiquement qui ne correspond pas à ce que votre framework écrit réellement.

Où trouver les paramètres

Ouvrez votre projet dans Orbit, allez à l'onglet Paramètres, et trouvez la carte Paramètres de build.

Champ	Ce qu'il fait	Espace réservé lorsqu'il est vide
Commande d'installation	Comment les dépendances sont installées avant le build	`npm ci (auto-detected)`
Commande de build	La commande qui produit votre sortie	`npm run build (auto-detected)`
Répertoire de sortie	Le dossier qu'Orbit publie après le build	`dist (auto-detected)`
Répertoire racine	Pour les monorepos, le sous-répertoire contenant votre application	`/ (monorepo subdirectory)`
Version Node.js	La version majeure de Node à utiliser pour construire et exécuter	Défaut de la plateforme

Laissez n'importe quel champ vide pour laisser Orbit le détecter automatiquement. Cliquez sur Enregistrer sur la carte des paramètres de build pour appliquer.

Carte des paramètres de build dans les paramètres du projet Orbit

Changer un paramètre de build ne change pas le déploiement actuellement en direct. Le nouveau paramètre s'applique à partir du prochain déploiement. Redéployez après l'enregistrement, sinon rien ne semblera avoir changé.

Paramètres par défaut des frameworks

Next.js

Next.js a deux modes dans Orbit, et choisir le mauvais est l'erreur la plus courante au premier déploiement.

Export statique (output: 'export' dans next.config.js) :

Commande de build : npm run build
Répertoire de sortie : out
Mode serveur : désactivé

Mode serveur (SSR ou ISR), qui correspond à la plupart des applications Next.js :

Activez le Mode serveur dans Paramètres, sous Runtime
Commande de build : npm run build
Répertoire de sortie : .next

Sans le mode serveur activé, une application Next.js rendue côté serveur est publiée comme des fichiers statiques. La page d'accueil se chargera généralement et chaque route dynamique affichera un 404. Si c'est votre symptôme, c'est votre cause : activez le mode serveur et redéployez avant de changer quoi que ce soit d'autre.

Astro

Le dossier de sortie d'Astro est dist dans tous les modes. Ce qui change, c'est si vous avez besoin du mode serveur.

output: 'static', la valeur par défaut : répertoire de sortie dist, mode serveur désactivé
output: 'server' ou output: 'hybrid' : répertoire de sortie dist, mode serveur activé
Commande de build : npm run build, ou astro build

Vite (React, Vue, Svelte)

Commande de build : npm run build, ou vite build
Répertoire de sortie : dist

Vite écrit toujours dans dist sauf si vous avez remplacé build.outDir dans vite.config.ts. Si vous l'avez fait, définissez le répertoire de sortie pour qu'il corresponde.

SvelteKit

Commande de build : npm run build
Répertoire de sortie : build

Si vous avez besoin du mode serveur dépend de votre adaptateur : un adaptateur statique ne le nécessite pas, un adaptateur Node le nécessite.

Nuxt 3

Commande de build : npm run build
Répertoire de sortie : .output
Mode serveur : activé

Remix

Commande de build : npm run build
Répertoire de sortie : build
Mode serveur : activé

Express ou une API Node simple

Commande de build : npm run build
Répertoire de sortie : dist
Mode serveur : activé

Le mode serveur exécute npm start après le build, assurez-vous donc que votre script start existe et démarre le serveur.

Create React App

Create React App est obsolète en amont et n'est pas un bon choix pour un nouveau projet, mais les projets existants compilent bien.

Commande de build : npm run build
Répertoire de sortie : build

HTML simple ou générateur de site statique

Laissez la commande d'installation vide s'il n'y a pas de package.json
Laissez la commande de build vide pour publier le référentiel tel quel, ou définissez la commande de votre générateur
Répertoire de sortie : . pour la racine du référentiel, ou quel que soit le dossier dans lequel le générateur écrit

Version Node.js

Entrez le numéro de version majeure uniquement : 18, 20 ou 22. L'indice du champ le dit explicitement. N'importe quoi d'autre, comme 20.11.0 ou v20, n'est pas ce que ce champ attend.

La version s'applique au build et, lorsque le mode serveur est activé, à l'exécution également.

Épinglez la version plutôt que de dépendre de la valeur par défaut. Une dépendance qui nécessite une version Node plus récente échoue pendant l'installation avec une erreur qui dit rarement « mauvaise version Node » en ces termes propres, et l'épinglette élimine entièrement cette classe d'échec.

Monorepos

Définissez le Répertoire racine sur le chemin de votre application, par exemple apps/web. Orbit se change dans ce répertoire avant d'exécuter vos commandes d'installation et de build, et le répertoire de sortie est alors relatif à celui-ci.

L'indice du champ énonce le deuxième comportement, plus utile : les poussées qui changent uniquement les fichiers en dehors de ce chemin sont ignorées automatiquement. Un monorepo avec quatre projets Orbit reconstruit uniquement les applications qu'un commit a réellement touchées, ce qui économise à la fois du temps et des minutes de build.

Chaque environnement peut remplacer le répertoire racine indépendamment, sous Staging : remplacements de build dans Paramètres, ce qui est utile lorsque le staging construit un espace de travail différent.

Remplacements de staging

Si votre projet a un environnement de staging, les Paramètres affichent une section Staging : remplacements de build avec les mêmes champs. N'importe quel champ laissé vide là-bas hérite de la valeur au niveau du projet, vous pouvez donc changer uniquement la commande de build pour le staging, par exemple à npm run build:staging, et laisser tout le reste tel quel.

Staging a ses propres paramètres connexes à proximité : une branche, un mot de passe d'accès, une liste blanche IP, l'auto-rollback en cas d'échec, et un bouton bascule Hériter les variables d'environnement de production.

Cache de build

Orbit cache node_modules entre les builds sur les plans Liftoff et Apex. La page de détail du déploiement affiche Cache hit ou Cold build, ainsi que la durée de la phase d'installation, pour que vous puissiez voir la valeur du cache sur votre projet.

Pour forcer une réinstallation complète, ouvrez Paramètres, cliquez sur Effacer le cache de build, et confirmez.

L'effacement du cache de build ne peut pas être annulé, et le prochain déploiement pour chaque environnement exécute une installation complète à partir de zéro. Sur un grand monorepo, c'est un build lent, faites-le intentionnellement plutôt que par réflexe.

Pièges courants

"Le build a réussi mais le site affiche un 404." Le répertoire de sortie est incorrect : Orbit a publié un dossier qui n'est pas votre sortie de build. Vérifiez quel dossier votre build crée réellement. Vite écrit dist, l'export statique Next.js écrit out, le mode serveur Next.js utilise .next, Create React App et Remix écrivent build, Nuxt écrit .output.

"404 uniquement sur les routes dynamiques, la page d'accueil va bien." Le mode serveur est désactivé sur une application qui en a besoin. Consultez la section Next.js ci-dessus.

"Module not found" au premier déploiement. Soit l'étape d'installation n'a pas été exécutée, soit elle a été exécutée avec un gestionnaire de packages différent de celui que vous utilisez localement. Définissez la commande d'installation explicitement : npm ci, yarn install --frozen-lockfile, ou pnpm install --frozen-lockfile. Vérifiez également que vous avez validé exactement un seul fichier de verrouillage : si à la fois package-lock.json et yarn.lock se trouvent dans le référentiel, le gestionnaire de packages détecté peut ne pas être celui que vous attendez.

"Fichier de verrouillage obsolète." npm ci et les équivalents frozen-lockfile refusent de fonctionner lorsque le fichier de verrouillage n'est pas d'accord avec package.json. Exécutez l'installation du gestionnaire de packages localement et validez le fichier de verrouillage régénéré. C'est l'échec de premier déploiement le plus courant et il ne se reproduit jamais localement, ce qui est exactement pourquoi c'est déroutant.

"Une seule application de mon monorepo se déploie." C'est le répertoire racine qui fait son travail. Chaque application a besoin de son propre projet Orbit avec son propre répertoire racine.

"Mauvaise version Node.js." Définissez le champ de version Node.js sur le numéro de version majeure uniquement.

Le build s'exécute à court de mémoire ou remplit le disque. Les deux sont des limites de plan sur la machine de build : Launch obtient 1 vCPU, 1 GB RAM et 4 GB de disque ; Liftoff obtient 2, 2 GB et 8 GB ; Apex obtient 4, 4 GB et 16 GB. L'ajout de NODE_OPTIONS=--max-old-space-size=2048 comme variable d'environnement aide seulement jusqu'à la RAM réelle de la machine. Voir Limites du plan Orbit.

Lectures connexes

Frameworks et runtimes supportés dans Orbit
Dépannage des builds échoués
Variables d'environnement pour la configuration au moment du build