Migración a NestJS 12: el backend vuelve a compilar y arrancar
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:
| Paquete | Antes de completar | Estado |
|---|---|---|
@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, schematics | ya en 12 | instalados |
@nestjs/schedule (añadido) | ^12.0.2 | exige Nest 11/12 y cron@4.4.0 |
cron (añadido) | ^3.2.1 | instalaba 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:
| Paquete | Antes | Ahora |
|---|---|---|
@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ón | Resultado |
|---|---|
npx tsc --noEmit | 0 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 cron | 15 jobs programados (backup.diario, alertas.vencimiento, clasificacion-abc.recalculo…) → cron 4 funciona en caliente |
GET /version | 200 |
GET /health | 200 |
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) exigetypescript >= 6.0.0@nestjs/swagger@12exigetypescript ^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érprete | Sin el flag | Con --experimental-vm-modules |
|---|---|---|
| Node 22.22.3 | SourceTextModule: undefined ❌ | hasAsyncGraph: undefined ❌ |
| Node 24.21.0 | SourceTextModule: 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 (crondeduplicado).ccf-almacen-api/.github/workflows/ci.ymlyrelease.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 alPATH, o usarnvm use 24.
