@backendkit-labs/nest-deploy

CLI de deploy para servicios NestJS. Compila el proyecto, empaqueta los archivos necesarios, instala dependencias de producción, corre migraciones TypeORM y genera un ZIP listo para subir al servidor.

Instalación

npm install --save-dev @backendkit-labs/nest-deploy

Configuración

Crear un archivo deploy.config.js en la raíz del proyecto:

/** @type {import('@backendkit-labs/nest-deploy').DeployConfig} */
module.exports = {
  name: 'api-middleware-service',
  environments: ['staging', 'production'],
  extraFiles: [],
  migrations: true,
  outputDir: '../',
  zip: true,
};

Opciones

| Campo | Tipo | Requerido | Default | Descripción | |---|---|---|---|---| | name | string | Sí | — | Nombre del servicio. Se usa como prefijo del directorio de salida | | environments | string[] | Sí | — | Entornos válidos. Debe existir un .env.<entorno> para cada uno | | extraFiles | string[] | No | [] | Archivos o carpetas adicionales a incluir en el paquete | | migrations | boolean | No | false | Si es true, corre npm run migration:run:dist antes de generar el ZIP | | outputDir | string | No | '../' | Directorio base donde se genera el paquete (relativo a la raíz del proyecto) | | zip | boolean | No | true | Si es true, genera un .zip además de la carpeta |

Requisitos del proyecto

Para que el CLI funcione correctamente el proyecto debe tener:

• npm run build — compila el proyecto a dist/
• .env.<entorno> — archivo de variables de entorno por entorno
• ecosystem.config.js — configuración de PM2 (opcional pero recomendado)

Si migrations: true, también necesita:

• npm run migration:run:dist — corre las migraciones desde el compilado

// package.json
{
  "scripts": {
    "migration:run:dist": "typeorm migration:run -d dist/database/data-source.js"
  }
}

Y el data-source.ts debe usar rutas relativas a __dirname para que funcione desde dist/:

migrations: [path.join(__dirname, '../migrations/*.{ts,js}')],

Uso

Agregar el script en package.json:

{
  "scripts": {
    "deploy": "nest-deploy"
  }
}

Modo interactivo

npm run deploy

El CLI pregunta el entorno y muestra las rutas de destino antes de ejecutar:

================================================
  @backendkit-labs/nest-deploy
================================================

Entorno [staging / production]: staging

  Servicio : api-middleware-service
  Entorno  : staging
  Destino  : /workspace/api-middleware-service-deploy-staging-20260610
  ZIP      : /workspace/api-middleware-service-deploy-staging-20260610.zip

Confirmar? [s/n]: s

[07:30:00] Compilando el proyecto (npm run build)...
  OK: Build completado

[07:30:18] Copiando archivos...
  OK: dist/
  OK: package.json
  OK: package-lock.json
  OK: ecosystem.config.js
  OK: .env.staging

[07:30:19] Instalando dependencias de produccion (npm install --omit=dev)...
  OK: node_modules instalado

[07:31:10] Ejecutando migraciones (migration:run:dist)...
  OK: Migraciones aplicadas

[07:31:12] Creando api-middleware-service-deploy-staging-20260610.zip...
  OK: api-middleware-service-deploy-staging-20260610.zip

================================================
  Paquete generado exitosamente
================================================
  Carpeta : /workspace/api-middleware-service-deploy-staging-20260610
  ZIP     : /workspace/api-middleware-service-deploy-staging-20260610.zip

  Para iniciar en el servidor:
    npm run migration:run:dist   # solo si hay migraciones pendientes
    pm2 start ecosystem.config.js --env staging
    pm2 save

Modo argumento (CI/scripts)

npm run deploy -- staging
npm run deploy -- production

# o directamente
npx nest-deploy staging
npx nest-deploy production

En modo argumento no pide confirmación — útil para pipelines de CI/CD.

Contenido del paquete generado

<name>-deploy-<env>-<fecha>/
├── dist/                  ← código compilado
├── node_modules/          ← solo dependencias de runtime
├── package.json
├── package-lock.json
├── ecosystem.config.js
└── .env.<entorno>

Iniciar en el servidor

Subir la carpeta o el ZIP al servidor y ejecutar:

# Solo si hay migraciones nuevas
npm run migration:run:dist

# Levantar con PM2
pm2 start ecosystem.config.js --env staging
pm2 save
pm2 startup

Uso con múltiples servicios

Cada servicio del ecosistema tiene su propio deploy.config.js. La librería se instala como devDependency en cada uno.

api-middleware-service/
├── deploy.config.js   → { name: 'api-middleware-service', migrations: true }

api-gateway/
├── deploy.config.js   → { name: 'api-gateway', migrations: false }

abac-microservice/
├── deploy.config.js   → { name: 'abac-microservice', migrations: true }

Todos comparten el mismo flujo: npm run deploy.