Empezar

Aplicaciones Node.js, Next.js y Nuxt.

Cómo se detectan y se inician los proyectos Node.js: versión de Node, gestor de paquetes, Next.js y Nuxt (como servidor o estáticos), SvelteKit, Astro, Express y compañía, la variable PORT y las migraciones de Prisma.

3 MIN DE LECTURA

Un repositorio con un package.json es un proyecto Node.js. Nosotros elegimos el framework, el gestor de paquetes y la versión de Node, lo compilamos y lo iniciamos: tú solo haces push.

Versión de Node y gestor de paquetes

  • Node.js: se toma de engines.node en package.json o de .nvmrc; la más reciente de 24, 22, 20, 18 o 16 que encaje. Si no hay ninguno de los dos, Node.js 22.
  • Gestor de paquetes: según el archivo de bloqueo: pnpm-lock.yaml → pnpm, yarn.lock → yarn; si no, npm (npm ci cuando hay un package-lock.json).
  • Compilación: el script build, si package.json lo tiene.

Frameworks

FrameworkCómo se ejecuta
Next.jscomo servidor (next start): el renderizado en servidor, las rutas de API y el middleware funcionan como siempre
Next.js con output: 'export'como sitio estático desde out
Nuxtcomo servidor (.output/server/index.mjs)
Nuxt con ssr: false y un script generatecomo sitio estático desde .output/public
SvelteKitcomo servidor con adapter-node; con adapter-static, como sitio estático
Astrocomo sitio estático; con @astrojs/node, como servidor
NestJSdist/main.js después de la compilación
Express, Fastify, Koa, Hono y otros servidoresel archivo de scripts.start (node server.js); si no, main; si no, server.js, app.js, index.js o main.js

Los proyectos solo de front-end —Vite, Create React App, Angular, Vue CLI y otros— se sirven como sitios estáticos; consulta Sitios estáticos.

Escucha en PORT

Un servidor debe escuchar en el puerto de la variable PORT, en todas las interfaces:

const port = process.env.PORT || 3000
app.listen(port, '0.0.0.0')

Next.js y Nuxt lo hacen por sí solos. Si tu aplicación escucha en un puerto fijo, no recibirá visitantes: el despliegue se detiene entonces en la comprobación de arranque y la versión anterior sigue funcionando.

Valores en tiempo de compilación

Las variables de la pestaña Variables llegan a la aplicación en ejecución, no a la compilación. Los valores que la compilación escribe en el código del cliente —como NEXT_PUBLIC_… en Next.js o VITE_…— se leen de tu repositorio, por ejemplo de un archivo .env.production incluido en un commit. El código del lado del servidor lee la pestaña Variables como siempre.

Tu propio comando de inicio

Si el inicio detectado no es el que quieres, define Ajustes → Ajustes de compilación → Comando de inicio, por ejemplo node dist/server.js o npm run start:prod. Ahí también puedes cambiar los comandos de instalación y de compilación.

Bases de datos y Prisma

Añade PostgreSQL o MySQL al proyecto y lee DATABASE_URL: se define por ti. Si tienes Prisma entre tus dependencias, el comando de release recomendado es npx prisma migrate deploy: se ejecuta en cada despliegue antes de que la nueva versión reciba visitantes. Consulta Despliegues.

Para colas con BullMQ, añade Valkey y usa REDIS_URL. Ejecuta el worker de la cola como worker en segundo plano: en la pestaña Procesos o como un servicio aparte con sus propios recursos. Consulta Servicios de un proyecto.

Archivos que sobreviven a un despliegue

Cada despliegue empieza desde una copia limpia de tu repositorio. Los archivos que tu aplicación escribe en /data se conservan entre despliegues y se copian a diario; todo lo que se escriba en otro sitio desaparece con el siguiente despliegue. Para subidas y archivos multimedia, el almacenamiento de objetos suele ser mejor opción.

Monorepos

En un repositorio con varios proyectos, define la Carpeta del proyecto al crear la aplicación (por ejemplo, apps/web). Otra carpeta del mismo repositorio puede ejecutarse como un servicio web aparte; consulta Servicios de un proyecto.

¿Sigues con dudas?

Escríbenos por chat: la AI responde al momento y un ingeniero se une cuando hace falta, a cualquier hora del día.

Contactar con soporte