upgrade-nestjs

Upgrade NestJS

When to use

• The user asks to upgrade NestJS, or to move off an unsupported or vulnerable version (10.x and older get no fixes; 11.x gets patches likely until the end of 2027).
• The installed @nestjs/core is below the applies_to range of backend/nestjs (12.x) and the user agrees to upgrade.
• The user wants to move queues from Bull (@nestjs/bull) to BullMQ (@nestjs/bullmq). That's a separate task from a version hop (Part B).

For a patch or minor upgrade within the same major, run only step 2 and Verify.

Before you start

• Read exact versions from the lockfile: every @nestjs/* package, @nestjs/cli, @nestjs/schematics, typescript, rxjs, reflect-metadata, the platform (express/fastify), the ORM, @nestjs/bull/bull and @nestjs/bullmq/bullmq, and the test runner. Run npx nest info.

• Read the Node version from .nvmrc, engines, the Dockerfile and CI, and the module format from package.json "type" and tsconfig.json module/moduleResolution.

• The working tree must be clean. Ask the user to commit or stash; work on a new branch (chore/nest-12).

• Ask the user:

  • the target (default: latest 12.x, currently 12.3.2) and whether to stop after each major for review;
  • whether the app runs on AWS Lambda or another runtime that needs extra flags;
  • whether network installs are approved. Follow the release-age cooldown in core/supply-chain; a security patch inside the cooldown needs the user's explicit exception.

• Plan the hops. One major at a time. nest upgrade only handles 11 → 12, so older apps hop manually first:

  NestJS	Node	TypeScript	Notes
  10.x	≥ 16	≥ 4.8.2	unsupported
  11.x	≥ 20	≥ 4.8.2 (5.x in practice)	Express 5, Fastify 5
  12.x	20.19+ or 22.12+ to run; CLI 22.22.3+, 24.15+ or 26+	≥ 6.0	ESM packages, loaded from CommonJS via require(esm)

  Move to Node 22 or 24 LTS before the 11 → 12 hop.

Steps

Part A: version upgrade