Frontends
Un frontend se despliega como cualquier otro repositorio: eliges el repositorio (y la carpeta, si es un monorepo) y la plataforma lo construye. Esta guía explica qué lee antes de construirlo y las decisiones que toma por ti.
Qué se detecta
La plataforma reconoce el framework en package.json y lee su configuración: Next.js, Nuxt, SvelteKit, Astro, Remix, React Router, Angular, Gatsby, Docusaurus, Eleventy, Vite y Create React App. De ahí saca cuatro respuestas:
| Pregunta | Ejemplos |
|---|---|
| Qué produce | Un servidor, una aplicación de una página, o páginas ya generadas |
| Dónde deja el resultado | dist, build, .output, dist/<proyecto>/browser… leído de la configuración, o supuesto con un aviso |
| Con qué se arranca | node server.js, node .output/server/index.mjs, react-router-serve… o nada, si son ficheros |
| Qué variables entran en la construcción | Las de prefijo público; ver abajo |
Puerto y dirección
El puerto lo decide la plataforma, con la variable PORT. Un sitio de ficheros se sirve con Caddy escuchando en $PORT, así que el puerto en el que escucha y el que se publica no pueden discrepar. Tiene que ser mayor que 1024: los contenedores arrancan sin privilegios.
Para lo que trae servidor propio, la plataforma fija la dirección: HOSTNAME para Next, NITRO_HOST para Nuxt y HOST para el resto, todas a 0.0.0.0. Un servidor atado a localhost dentro de un contenedor no responde a nadie.
Sobre qué se construye
Sobre Debian, no Alpine: esbuild, lightningcss, el motor de Tailwind o sharp publican binarios que no existen para musl, y en Alpine fallan con un Cannot find module '@…-linux-x64-musl'. La imagen sigue además a tu gestor de paquetes: con Bun, la variante Debian de Bun; si no, la de Node.
Enlaces profundos
- En una aplicación de una página, cualquier ruta que no sea un fichero devuelve
index.html, para que los enlaces profundos funcionen. - En un sitio de páginas generadas, una ruta que no existe devuelve un 404 de verdad, en vez de la portada con un 200.
Next.js
Con output: 'standalone' en next.config, la imagen lleva solo lo necesario, y la plataforma copia además .next/static y public, que el modo standalone no incluye.
Si tu next.config no declara standalone, se avisa y se copia el proyecto entero (cientos de megas de más); la plataforma no reescribe tu configuración. Si el repositorio no trae ningún next.config, se genera uno.
En un monorepo, next.config necesita outputFileTracingRoot apuntando a la raíz del repositorio, o el standalone deja fuera los paquetes hermanos.
Variables que entran en el build
Los bundlers sustituyen VITE_API_URL y compañía al compilar: una variable que no esté presente durante la construcción es undefined en producción. Por eso la plataforma pasa a la construcción las variables del servicio con prefijo público:
VITE_, NEXT_PUBLIC_, PUBLIC_, REACT_APP_, GATSBY_, EXPO_PUBLIC_, NG_APP_, STORYBOOK_
Una variable secreta con uno de esos prefijos no se pasa, y el registro de la construcción la nombra: su valor acabaría dentro del JavaScript que descarga cualquier visitante. NUXT_PUBLIC_ no está en la lista porque Nuxt la lee al arrancar, no al compilar.
Cambiar una de estas variables reconstruye la imagen en el siguiente despliegue.