Configurar tu Comando de Compilacion y Directorio de Salida

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…

Configurar tu comando de compilación y directorio de salida

Lograr que Orbit compile tu proyecto correctamente se reduce a un puñado de campos en Settings: comando de instalación, comando de compilación, directorio de salida, directorio raíz y versión de Node.js. Si se dejan en blanco, se detectan automáticamente, y la mayoría de los problemas en el primer despliegue provienen de un valor detectado automáticamente que no coincide con lo que tu framework realmente escribe.

Dónde encontrar la configuración

Abre tu proyecto en Orbit, ve a la pestaña Settings y busca la tarjeta Build settings.

Campo	Qué hace	Marcador de posición cuando está en blanco
Install command	Cómo se instalan las dependencias antes de la compilación	`npm ci (auto-detected)`
Build command	El comando que produce tu salida	`npm run build (auto-detected)`
Output directory	La carpeta que Orbit publica después de la compilación	`dist (auto-detected)`
Root directory	Para monorepos, el subdirectorio que contiene tu aplicación	`/ (monorepo subdirectory)`
Node.js version	La versión principal de Node a usar para compilar y ejecutar	Platform default

Deja cualquier campo en blanco para permitir que Orbit lo detecte automáticamente. Haz clic en Save en la tarjeta Build settings para aplicar.

Tarjeta de configuración de compilación en la configuración del proyecto Orbit

Cambiar una configuración de compilación no cambia el despliegue que está actualmente en vivo. La nueva configuración se aplica desde el próximo despliegue. Redespliega después de guardar, o nada parecerá haber sucedido.

Valores predeterminados del framework

Next.js

Next.js tiene dos modos en Orbit, y elegir el incorrecto es el error más común en el primer despliegue.

Exportación estática (output: 'export' en next.config.js):

Comando de compilación: npm run build
Directorio de salida: out
Modo de servidor: desactivado

Modo de servidor (SSR o ISR), que es la mayoría de las aplicaciones Next.js:

Activa Server mode en Settings, bajo Runtime
Comando de compilación: npm run build
Directorio de salida: .next

Sin el modo de servidor habilitado, una aplicación Next.js renderizada en servidor se publica como archivos estáticos. La página de inicio generalmente cargará y cada ruta dinámica resultará en 404. Si ese es tu síntoma, esta es tu causa: activa el modo de servidor y redespliega antes de cambiar cualquier otra cosa.

Astro

La carpeta de salida de Astro es dist en todos los modos. Lo que cambia es si necesitas modo de servidor.

output: 'static', el predeterminado: directorio de salida dist, modo de servidor desactivado
output: 'server' o output: 'hybrid': directorio de salida dist, modo de servidor activado
Comando de compilación: npm run build, o astro build

Vite (React, Vue, Svelte)

Comando de compilación: npm run build, o vite build
Directorio de salida: dist

Vite siempre escribe en dist a menos que hayas anulado build.outDir en vite.config.ts. Si lo has hecho, establece el directorio de salida para que coincida.

SvelteKit

Comando de compilación: npm run build
Directorio de salida: build

Si necesitas modo de servidor depende de tu adaptador: un adaptador estático no lo necesita, un adaptador Node sí.

Nuxt 3

Comando de compilación: npm run build
Directorio de salida: .output
Modo de servidor: activado

Remix

Comando de compilación: npm run build
Directorio de salida: build
Modo de servidor: activado

Express o una API Node sin formato

Comando de compilación: npm run build
Directorio de salida: dist
Modo de servidor: activado

El modo de servidor ejecuta npm start después de la compilación, así que asegúrate de que tu script start existe e inicia el servidor.

Create React App

Create React App está deprecado en la rama principal y no es una buena opción para un nuevo proyecto, pero los existentes se compilan sin problemas.

Comando de compilación: npm run build
Directorio de salida: build

HTML sin formato o generador de sitios estáticos

Deja el comando de instalación en blanco si no hay package.json
Deja el comando de compilación en blanco para publicar el repositorio tal cual, o establece el comando de tu generador
Directorio de salida: . para la raíz del repositorio, o la carpeta en la que el generador escribe

Versión de Node.js

Ingresa solo el número de versión principal: 18, 20 o 22. La sugerencia del campo lo dice explícitamente. Cualquier otra cosa, como 20.11.0 o v20, no es lo que este campo espera.

La versión se aplica a la compilación y, cuando el modo de servidor está activado, al tiempo de ejecución también.

Fija la versión en lugar de confiar en el valor predeterminado. Una dependencia que necesita una versión más nueva de Node falla durante la instalación con un error que rara vez dice "wrong Node version" explícitamente, y fijar la versión elimina completamente esa clase de falla.

Monorepos

Establece Root directory en la ruta de tu aplicación, por ejemplo apps/web. Orbit cambia a ese directorio antes de ejecutar tus comandos de instalación y compilación, y el directorio de salida es entonces relativo a él.

La sugerencia del campo explica el segundo comportamiento, más útil: los cambios que solo afectan archivos fuera de esa ruta se omiten automáticamente. Un monorepo con cuatro proyectos de Orbit se recompila solo en las aplicaciones que un commit realmente tocó, lo que ahorra tanto tiempo como minutos de compilación.

Cada entorno puede anular el directorio raíz independientemente, bajo Staging: build overrides en Settings, lo cual es útil cuando la compilación de staging necesita un workspace diferente.

Anulaciones de staging

Si tu proyecto tiene un entorno de staging, Settings muestra una sección Staging: build overrides con los mismos campos. Cualquier campo dejado en blanco allí hereda el valor a nivel del proyecto, así que puedes cambiar solo el comando de compilación para staging, por ejemplo a npm run build:staging, y dejar todo lo demás sin cambios.

Staging tiene su propia configuración relacionada cercana: una rama, una contraseña de acceso, una lista blanca de IP, reversión automática ante fallos, y un toggle Inherit production env vars.

Caché de compilación

Orbit almacena en caché node_modules entre compilaciones en los planes Liftoff y Apex. La página de detalle del despliegue muestra Cache hit o Cold build, junto con la duración de la fase de instalación, para que puedas ver cuánto vale el caché en tu proyecto.

Para forzar una reinstalación completa, abre Settings, haz clic en Clear build cache y confirma.

Limpiar el caché de compilación no se puede deshacer, y el próximo despliegue para cada entorno ejecuta una instalación completa desde cero. En un monorepo grande eso es una compilación lenta, así que hazlo deliberadamente en lugar de como un reflejo.

Problemas comunes

"La compilación se completó pero el sitio muestra un 404." El directorio de salida es incorrecto: Orbit publicó una carpeta que no es tu salida de compilación. Verifica qué carpeta tu compilación realmente crea. Vite escribe en dist, Next.js con exportación estática escribe en out, Next.js en modo de servidor usa .next, Create React App y Remix escriben en build, Nuxt escribe en .output.

"404 solo en rutas dinámicas, la página de inicio está bien." El modo de servidor está desactivado en una aplicación que lo necesita. Consulta la sección Next.js anterior.

"Module not found" en el primer despliegue. O el paso de instalación no se ejecutó, o se ejecutó con un gestor de paquetes diferente del que usas localmente. Establece el comando de instalación explícitamente: npm ci, yarn install --frozen-lockfile, o pnpm install --frozen-lockfile. También verifica que hayas comprometido exactamente un archivo de bloqueo: si tanto package-lock.json como yarn.lock están en el repositorio, el gestor de paquetes detectado puede no ser el que esperas.

"Lockfile out of date." npm ci y los equivalentes de frozen-lockfile se rehúsan a ejecutarse cuando el archivo de bloqueo no coincide con package.json. Ejecuta la instalación de tu gestor de paquetes localmente y compromete el archivo de bloqueo regenerado. Este es el error de primer despliegue más común y nunca se reproduce localmente, lo cual es exactamente por qué es confuso.

"Solo una aplicación en mi monorepo se está desplegando." Ese es el directorio raíz haciendo su trabajo. Cada aplicación necesita su propio proyecto de Orbit con su propio directorio raíz.

"Versión incorrecta de Node.js." Establece el campo de versión de Node.js solo al número de versión principal.

La compilación se queda sin memoria o llena el disco. Ambos son límites de plan en la máquina de compilación: Launch obtiene 1 vCPU, 1 GB de RAM y 4 GB de disco; Liftoff obtiene 2, 2 GB y 8 GB; Apex obtiene 4, 4 GB y 16 GB. Agregar NODE_OPTIONS=--max-old-space-size=2048 como una variable de entorno ayuda solo hasta la RAM real de la máquina. Consulta Orbit Plan Limits.

Lecturas relacionadas

Marcos de trabajo y tiempos de ejecución compatibles en Orbit
Solución de problemas de compilaciones fallidas
Variables de entorno para configuración en tiempo de compilación