Saltar al contenido principal

Migración a NestJS 12: el backend vuelve a compilar y arrancar

· 5 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

El backend no arrancaba:

src/common/jobs/jobs.service.ts:176:60 - error TS2345: Argument of type
'CronJob<any, null>' is not assignable to parameter of type 'CronJob<null, null>'.

jobs.service.ts estaba intacto desde el 4 de octubre: no era un bug de código, era el síntoma de una migración a NestJS 12 a medias hecha en package.json (instalada el mismo día).


🔎 Causa raíz​

package.json había subido casi todo @nestjs/* a la v12, pero dejó atrás la pieza clave:

PaqueteAntes de completarEstado
@nestjs/common^10.4.15 (instalado 10.4.19)⚠️ la v12 exige que sea 12
@nestjs/core, config, swagger, serve-static, websockets, platform-express, platform-socket.io, testing, schematicsya en 12instalados
@nestjs/schedule (añadido)^12.0.2exige Nest 11/12 y cron@4.4.0
cron (añadido)^3.2.1instalaba 3.2.1 arriba

npm ls marcaba el árbol como inválido en todas partes. Y convivían dos copias de cron: la 3.2.1 que resolvía import { CronJob } from 'cron' y la 4.4.0 anidada bajo @nestjs/schedule@12. Dos clases CronJob distintas de dos paquetes distintos no son asignables entre sí, y ahí estaba el TS2345 — los miembros que TypeScript decía que faltaban (waitForCompletion, threshold, _isActive, _isCallbackRunning) son exactamente los internos de la v4.

🛠️ Qué se hizo​

Se completó la migración alineando todo el conjunto a la v12:

PaqueteAntesAhora
@nestjs/common^10.4.15^12.1.2
@nestjs/cli (dev)^10.0.0^12.0.8
@nestjs/jwt^10.2.0^12.0.2
@nestjs/passport^10.0.3^12.0.0
@nestjs/typeorm^11.0.0^12.0.2
@nestjs/bullmq^11.0.5^12.0.0
@nestjs/throttler^6.4.0^6.7.1 (ya soporta common 12)
@nestjs/mapped-types*^12.0.0 (dejar de resolver a ciegas)
cron^3.2.1^4.4.0

Tras instalar, cron queda como copia única en 4.4.0 (la anidada desapareció) y @nestjs/common pasa a 12.1.2.

No hizo falta tocar ni una línea de código. El código ya estaba preparado: proximaEjecucion() castea el resultado de nextDate() y llama a toJSDate(), que es precisamente la API de luxon que introdujo cron 4; la firma posicional del constructor new CronJob(cron, onTick, null, false) sigue siendo válida; y las APIs de @nestjs/schedule que usa el proyecto (ScheduleModule, CronExpression, SchedulerRegistry.addCronJob/getCronJob/deleteCronJob) son idénticas en la v12.

✅ Verificación​

ComprobaciónResultado
npx tsc --noEmit0 errores (el TS2345 desapareció)
npm run build (nest build)exit 0
npm run start:dev (nest start --watch)Found 0 errors y Nest application successfully started en 0.0.0.0:4000
Jobs cron15 jobs programados (backup.diario, alertas.vencimiento, clasificacion-abc.recalculo…) → cron 4 funciona en caliente
GET /version200
GET /health200
GET /api (Swagger)200 → Express 5 y Swagger 12 enrutan bien
npm test (Node 24.21.0 + --experimental-vm-modules)123 suites / 1164 pruebas en verde, 0 fallos

⚠️ Dos incompatibilidades de dependencias (documentadas)​

1. La instalación necesita --legacy-peer-deps. Los peers de NestJS 12 son mutuamente incompatibles hoy:

  • @nestjs/schematics@12 (vía @nestjs/cli@12) exige typescript >= 6.0.0
  • @nestjs/swagger@12 exige typescript ^5.5.0 || ^6.0.0
  • TypeScript 6 solo existe en beta; el estable actual es 7.0.2, que incumple el peer de swagger.

No hay ninguna versión estable de TypeScript que satisfaga a los dos, así que una instalación sin avisos no es posible hoy. Se mantiene TypeScript 5.8.3 (con el que todo compila y arranca) y el flag queda documentado. ci.yml y release.yml se actualizaron en consecuencia.

2. Las pruebas necesitan Node ≥ 24.9 y --experimental-vm-modules. NestJS 12 se distribuye como ESM puro ("type": "module", sin build CommonJS) y las suites lo importan desde CommonJS. Node 22 sí puede require()-lo —por eso el backend arranca—, pero Jest no: aborta con «Must use import to load ES Module».

La causa exacta está en el propio Jest (jest-runtime):

const supportsSyncEvaluate =
typeof vm.SourceTextModule?.prototype?.hasAsyncGraph === 'function';

No es una comprobación de versión sino de capacidad, y hacen falta las dos cosas. Comprobado variable por variable:

IntérpreteSin el flagCon --experimental-vm-modules
Node 22.22.3SourceTextModule: undefined ❌hasAsyncGraph: undefined ❌
Node 24.21.0SourceTextModule: undefined ❌hasAsyncGraph: function ✅

Es decir: Node 24 solo no basta (le falta el flag) y el flag solo tampoco (le falta hasAsyncGraph, que llega en Node 24.9). Con ambos, la suite completa queda 123 suites / 1164 pruebas en verde.

Los scripts de npm ya invocan a Node con el flag (node --experimental-vm-modules node_modules/jest/bin/jest.js), y un preflight (scripts/verificar-node-pruebas.js, enganchado en pretest) avisa con un mensaje claro cuando el Node instalado es anterior a 24.9, en vez de dejar el error críptico de Jest.

3. nest-winston@1.10.2 declara peer @nestjs/common ^5 || … || ^11 (aún no oficial para 12). Es un aviso, no un fallo: el logger Winston inicializa correctamente en el arranque verificado.

📌 Archivos tocados​

  • ccf-almacen-api/package.json — 9 versiones alineadas a NestJS 12 y scripts de prueba con --experimental-vm-modules.
  • ccf-almacen-api/scripts/verificar-node-pruebas.js — preflight que exige Node ≥ 24.9 para las pruebas.
  • ccf-almacen-api/package-lock.json — resolución actualizada (cron deduplicado).
  • ccf-almacen-api/.github/workflows/ci.yml y release.yml — Node 24 e instalación con --legacy-peer-deps.

🧭 Nota sobre el análisis de TypeScript​

Se evaluó subir TypeScript para eliminar el --legacy-peer-deps, y el propio semver de npm lo descarta: ninguna versión disponible cumple los dos peers a la vez.

Versión@nestjs/schematics 12 (>=6.0.0)@nestjs/swagger 12 (^5.5 || ^6)
5.8.3❌✅
6.0.0-beta❌ (un prerelease no satisface un rango sin prerelease)❌
7.0.2✅❌

Por eso se mantiene TypeScript 5.8.3, con el que todo compila, arranca y pasa las pruebas.

Nota operativa: en este equipo se dejó una copia portable de Node 24.21.0 en .herramientas/node-v24.21.0-win-x64/ (en la raíz del monorepo, fuera de los repositorios, para no ensuciarlos). El Node por defecto del sistema sigue siendo el 22.22.3 y no se tocó: para ejecutar las pruebas hay que anteponer esa carpeta al PATH, o usar nvm use 24.