Node.js

Kubiy ejecuta aplicaciones Node.js usando PM2 como process manager. PM2 gestiona el proceso, lo reinicia si falla y mantiene los logs disponibles.

Presets disponibles

npm run [script]

Ejecuta un script definido en tu package.json. Este es el preset recomendado para la mayoría de los proyectos.

Parámetro	Valor
startMode	npm
Target por defecto	start
Build por defecto	npm ci --omit=dev

Ejemplo de configuración:

Preset:  npm run [script]
Script:  start

PM2 ejecutará internamente: npm run start

node [archivo]

Ejecuta un archivo JavaScript directamente con Node.js.

Parámetro	Valor
startMode	node
Target por defecto	index.js
Build por defecto	npm ci --omit=dev

Ejemplo de configuración:

Preset:  node [archivo]
Archivo: server.js

PM2 ejecutará internamente: node server.js

:::tip Cuándo usar cada preset Usa npm run si tienes scripts definidos en package.json (lo más común). Usa node si quieres ejecutar directamente un archivo sin pasar por npm, por ejemplo en proyectos muy ligeros sin scripts personalizados. :::

Puerto

Tu app debe leer el puerto desde la variable de entorno PORT. Kubiy siempre inyecta esta variable.

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

El valor por defecto si no se lee PORT es 3000, pero debes siempre usar la variable de entorno para evitar conflictos.

Build Command

Si dejas el campo Build Command vacío, Kubiy ejecuta:

npm ci --omit=dev

Esto instala exactamente las dependencias de package-lock.json, excluyendo devDependencies. Es el comportamiento recomendado para producción.

Si necesitas un proceso de build (TypeScript, bundlers, etc.), especifica el comando completo:

npm ci && npm run build

aviso

Cuando especificas un Build Command, reemplaza completamente la instalación automática. Si olvidas incluir npm ci o npm install, las dependencias no se instalarán.

Ver la referencia completa de Build Command.

Casos de uso comunes

Express / Fastify / Hapi

{
  "scripts": {
    "start": "node server.js"
  }
}

Configuración en Kubiy:

Preset:  npm run [script]
Script:  start

Next.js (modo servidor)

{
  "scripts": {
    "build": "next build",
    "start": "next start"
  }
}

Configuración en Kubiy:

Preset:       npm run [script]
Script:       start
Build Command: npm ci && npm run build

NestJS

{
  "scripts": {
    "build": "nest build",
    "start:prod": "node dist/main"
  }
}

Configuración en Kubiy:

Preset:       npm run [script]
Script:       start:prod
Build Command: npm ci && npm run build

TypeScript con ts-node-esm

Si tu proyecto corre directamente con ts-node (sin build step):

{
  "scripts": {
    "start": "ts-node src/index.ts"
  }
}

Preset:       npm run [script]
Script:       start
Build Command: npm ci

aviso

ts-node en producción no es recomendable para apps con alto tráfico. Considera compilar a JavaScript con tsc y ejecutar el output.

Monorepo con subdirectorio

Si tu app Node.js está en apps/api/:

Subdirectorio: apps/api
Preset:        npm run [script]
Script:        start

Kubiy usará apps/api/ como raíz del proyecto para el build y el inicio.

Variables de entorno disponibles

Variable	Descripción
PORT	Puerto asignado (default 3000)
APP_PORT	Alias de PORT
NODE_ENV	No se inyecta automáticamente — configúrala tú si tu app la necesita
KUBIY_DEPLOY_ID	ID del deploy actual
KUBIY_APP_ID	ID de la aplicación

consejo

Agrega NODE_ENV=production en la sección de variables de entorno si tu app lo necesita para deshabilitar logs de debug u optimizar rendimiento.

Health Check recomendado

Implementa un endpoint /health sencillo:

app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', uptime: process.uptime() })
})

Configura en Kubiy:

Health Check Path: /health

Kubiy intentará 25 veces con 1 segundo de intervalo. Si tu app tarda en inicializar (por ejemplo, conexión a base de datos), asegúrate de que el endpoint /health solo responda 200 cuando la app esté lista.

Troubleshooting

La app no inicia — "Cannot find module"

El módulo no está instalado. Causas comunes:

1. El paquete está en devDependencies y el build command usa --omit=dev. Mueve la dependencia a dependencies.
2. El package-lock.json está desactualizado. Corre npm install localmente y sube el lock file actualizado.
3. Especificaste un Build Command que no incluye npm install. Asegúrate de que tu comando instala dependencias.

La app inicia pero el health check falla

1. Verifica que la app escucha en process.env.PORT, no en un puerto hardcodeado.
2. Verifica que el endpoint de health check devuelve HTTP 200.
3. Si la app tarda más de 25 segundos en inicializar, considera diferir la respuesta del health check hasta que la app esté lista, o aumentar el tiempo de inicialización.

PM2 reinicia la app en loop

La app está crasheando al inicio. Revisa los logs del deploy para ver el error. Causas comunes:

• Falta de variables de entorno requeridas
• Error de sintaxis en el código
• Dependencias faltantes

Build falla con "npm ci" — "Missing package-lock.json"

El package-lock.json no está en el repositorio. Tienes dos opciones:

1. Generar el lock file localmente (npm install) y subirlo al repo
2. Cambiar el Build Command a npm install (menos reproducible pero funciona sin lock file)

Next.js: error "Port already in use"

Next.js toma el puerto de PORT automáticamente desde v13+. En versiones anteriores, pasa el flag explícitamente:

{
  "scripts": {
    "start": "next start -p $PORT"
  }
}

El deploy tarda mucho

Si npm ci tarda varios minutos, considera:

1. Usar un .npmignore para no subir node_modules al repo
2. Revisar si tienes dependencias muy pesadas que podrían reemplazarse
3. Separar las dependencias de producción de las de desarrollo correctamente