Orbit
Marcos de Trabajo y Tiempos de Ejecución Compatibles en Orbit
Orbit builds any project that installs with npm, yarn or pnpm and produces a folder of files or a Node.js server, and it detects the framework and package manager for you so most projects deploy…
Orbit construye cualquier proyecto que se instale con npm, yarn o pnpm y produzca una carpeta de archivos o un servidor Node.js, y detecta el framework y el gestor de paquetes automáticamente para que la mayoría de los proyectos se desplieguen sin ninguna configuración de compilación. Esta guía cubre qué se detecta, la configuración que necesita cada framework común, cuándo debe activar el modo servidor y cómo elegir una versión de Node.js.
Lo Que Orbit Detecta Automáticamente
Cuando se ejecuta una compilación, Orbit registra lo que encontró y te lo muestra:
- Framework, en la página de detalles de despliegue y como un distintivo en las tarjetas de despliegue en la descripción general del proyecto.
- Gestor de paquetes, elegido de tu archivo de bloqueo:
package-lock.jsonproporciona npm,yarn.lockproporciona yarn,pnpm-lock.yamlproporciona pnpm.
La configuración de compilación en Settings es completamente opcional. Deja un campo en blanco y su placeholder te indica qué se usará en su lugar: Install command muestra npm ci (auto-detected), Build command muestra npm run build (auto-detected), y Output directory muestra dist (auto-detected).
Confirma exactamente un archivo de bloqueo. Si tanto package-lock.json como yarn.lock están en el repositorio, el gestor de paquetes que Orbit elige puede no ser el que usas localmente, y obtendrás una instalación que se comporta de manera diferente a tu máquina sin razón visible. Elimina el que no estés usando.
Configuración Por Framework
Estos son los valores que necesita cada framework. Donde Orbit envía una plantilla inicial para el framework, la plantilla usa exactamente esta configuración.
| Framework | Comando de compilación | Directorio de salida | Modo servidor |
|---|---|---|---|
| Next.js, exportación estática | npm run build | out | Desactivado |
| Next.js, SSR o ISR | npm run build | .next | Activado |
| Astro, estático | astro build | dist | Desactivado |
| Astro, servidor o híbrido | astro build | dist | Activado |
| Vite (React, Vue, Svelte) | npm run build | dist | Desactivado |
| SvelteKit | npm run build | build | Depende del adaptador |
| Nuxt 3 | npm run build | .output | Activado |
| Remix | npm run build | build | Activado |
| Express o una API Node simple | npm run build | dist | Activado |
| Create React App | npm run build | build | Desactivado |
| HTML simple o generador estático | dejar en blanco, o el comando de tu generador | . o la carpeta en la que escribe | Desactivado |
Vite siempre escribe en dist a menos que hayas configurado build.outDir en vite.config.ts. La carpeta de salida de Astro es dist en cada modo; lo que cambia entre modos es si necesitas modo servidor, no dónde caen los archivos.
Modo Servidor
Modo servidor es un conmutador en Settings, bajo Runtime. Cuando está activado, Orbit mantiene viva la máquina de compilación ejecutando npm start después de cada despliegue en lugar de servir una carpeta de archivos estáticos.
Actívalo para Next.js con SSR, Remix, Nuxt, una API Express, y cualquier otra cosa que no sea una exportación estática. Déjalo desactivado para una compilación genuinamente estática.
Se aplica desde el próximo despliegue, no al despliegue que está actualmente en directo.
El síntoma clásico de un modo servidor faltante es un sitio donde la página principal se carga perfectamente y cada ruta dinámica devuelve un 404. La compilación tuvo éxito, los archivos fueron publicados, y simplemente no hay ningún servidor ejecutándose para responder a las rutas. Si eso es lo que ves, activa el modo servidor y vuelve a desplegar antes de cambiar cualquier otra cosa.
Versión de Node.js
Establece Node.js version en Settings bajo Build settings. Ingresa el número de versión principal únicamente: 18, 20 o 22. Déjalo en blanco para usar el valor predeterminado de la plataforma.
La versión se aplica tanto a la compilación como a, cuando el modo servidor está activado, el tiempo de ejecución.
Fija la versión explícitamente en lugar de depender del valor predeterminado. Una dependencia que requiere un Node más nuevo que el valor predeterminado falla la instalación con un error que no dice obviamente eso, y fijar la versión elimina toda una clase de fallos de compilación "funcionó ayer".
Monorepos
Establece Root directory al subdirectorio que contiene la aplicación, por ejemplo apps/web. Orbit cambia a ese directorio antes de ejecutar tus comandos de instalación y compilación.
También hace algo que quieres pero que podrías no esperar: los pushes que solo cambian archivos fuera de esa ruta se omiten automáticamente. Un monorepo con cuatro proyectos Orbit por lo tanto reconstruye solo las aplicaciones que un commit realmente tocó.
Cada entorno puede sobrescribir el directorio raíz por separado, bajo Staging: build overrides en Settings, lo cual es útil cuando el staging compila un workspace diferente.
Configuración de Compilación Personalizada
Sobrescribe cualquier cosa en Settings, bajo Build settings:
| Campo | Ejemplo | Notas |
|---|---|---|
| Comando de instalación | npm ci | O yarn install --frozen-lockfile, pnpm install --frozen-lockfile |
| Comando de compilación | npm run build:prod | Ejecuta exactamente como está escrito |
| Directorio de salida | dist/client | La carpeta publicada después de la compilación |
| Directorio raíz | apps/frontend | Subdirectorio monorepo |
| Versión de Node.js | 20 | Solo versión principal |
En blanco significa autodetección. Haz clic en Save en la tarjeta de Build settings para aplicar.
Staging puede sobrescribir cualquiera de estos independientemente, en la sección Staging: build overrides. Un campo dejado en blanco allí hereda el valor a nivel de proyecto, así que puedes cambiar solo el comando de compilación para staging y dejar todo lo demás igual.
Caché de Compilación
Orbit almacena en caché node_modules entre compilaciones en los planes Liftoff y Apex. Cuando se usa el caché, el despliegue muestra un distintivo Cache hit y la fase de instalación es mucho más corta. Una compilación sin él muestra Cold build.
Para forzar una reinstalación completa, abre Settings, luego Clear build cache, y confirma. El próximo despliegue para cada entorno ejecuta una instalación completa desde cero. Esto no se puede deshacer, y la compilación posterior será lenta.
Recursos de la Máquina de Compilación
El tamaño de la máquina de compilación depende de tu plan, lo cual importa para compilaciones grandes:
| Plan | vCPU | RAM | Disco | Límite de tiempo |
|---|---|---|---|---|
| Launch | 1 | 1 GB | 4 GB | 30 minutos |
| Liftoff | 2 | 2 GB | 8 GB | 30 minutos |
| Apex | 4 | 4 GB | 16 GB | 30 minutos |
Una compilación que se queda sin memoria o llena su disco falla con esa categoría de fallo nombrada en la página de despliegue. Aumentar NODE_OPTIONS=--max-old-space-size ayuda solo hasta la RAM actual de la máquina.
Comenzar Desde una Plantilla
Si quieres un despliegue funcional antes de tener un repositorio, usa una plantilla inicial. En New project, cambia de Import Git Repo a Start from Template y elige una: Next.js con shadcn/ui, un sitio de marketing de Astro, Remix Indie Stack, un iniciador de SvelteKit, una aplicación Nuxt 3 mínima, o una API REST de Express. Orbit copia la plantilla, aplica la configuración de compilación correcta, y la despliega.
Lectura Relacionada
- Configuring Your Build Command and Output Directory para el detalle por framework y los errores habituales
- Troubleshooting Failed Builds
- Orbit Plan Limits