@nx/nest 24.0.6 → 24.1.0-canary.20261111-edd9940

package/dist/src/generators/application/application.js

@@ -8,6 +8,7 @@ const init_1 = require("../init/init");
 const lib_1 = require("./lib");
 const assert_supported_nestjs_version_1 = require("../../utils/assert-supported-nestjs-version");
 const assert_vitest_supported_1 = require("../../utils/assert-vitest-supported");
+const unit_test_runner_1 = require("../../utils/unit-test-runner");
 const ensure_dependencies_1 = require("../../utils/ensure-dependencies");
 async function applicationGenerator(tree, rawOptions) {
     return await applicationGeneratorInternal(tree, {
@@ -18,6 +19,9 @@ async function applicationGenerator(tree, rawOptions) {
 async function applicationGeneratorInternal(tree, rawOptions) {
     (0, assert_supported_nestjs_version_1.assertSupportedNestJsVersion)(tree);
     const options = await (0, lib_1.normalizeOptions)(tree, rawOptions);
+    if (options.unitTestRunner === 'jest') {
+        (0, unit_test_runner_1.assertJestSupported)(tree);
+    }
     if (options.unitTestRunner === 'vitest') {
         (0, assert_vitest_supported_1.assertVitestSupported)(tree);
     }
@@ -29,6 +33,9 @@ async function applicationGeneratorInternal(tree, rawOptions) {
     tasks.push(initTask);
     const nodeApplicationTask = await (0, node_1.applicationGenerator)(tree, (0, lib_1.toNodeApplicationGeneratorOptions)(options));
     tasks.push(nodeApplicationTask);
+    if (options.unitTestRunner === 'jest' && (0, unit_test_runner_1.usesEsmOnlyNestJs)(tree)) {
+        tasks.push((0, unit_test_runner_1.configureJestForEsmOnlyNestJs)(tree, options.appProjectName));
+    }
     (0, lib_1.createFiles)(tree, options);
     (0, lib_1.updateTsConfig)(tree, options);
     if (!options.skipPackageJson) {

package/dist/src/generators/application/lib/normalize-options.js

@@ -4,24 +4,26 @@ exports.normalizeOptions = normalizeOptions;
 exports.toNodeApplicationGeneratorOptions = toNodeApplicationGeneratorOptions;
 const internal_1 = require("@nx/devkit/internal");
 const internal_2 = require("@nx/js/internal");
+const unit_test_runner_1 = require("../../../utils/unit-test-runner");
 async function normalizeOptions(tree, options) {
     await (0, internal_1.ensureRootProjectName)(options, 'application');
-    const { projectName: appProjectName, projectRoot: appProjectRoot } = await (0, internal_1.determineProjectNameAndRootOptions)(tree, {
+    const { projectName, projectRoot: appProjectRoot, importPath, } = await (0, internal_1.determineProjectNameAndRootOptions)(tree, {
         name: options.name,
         projectType: 'application',
         directory: options.directory,
         rootProject: options.rootProject,
     });
     options.rootProject = appProjectRoot === '.';
+    const isUsingTsSolutionConfig = (0, internal_2.isUsingTsSolutionSetup)(tree);
     return {
         ...options,
         strict: options.strict ?? false,
-        appProjectName,
+        appProjectName: isUsingTsSolutionConfig && !options.name ? importPath : projectName,
         appProjectRoot,
         linter: await (0, internal_2.normalizeLinterOption)(tree, options.linter),
-        unitTestRunner: options.unitTestRunner ?? 'jest',
+        unitTestRunner: options.unitTestRunner ?? (0, unit_test_runner_1.getDefaultUnitTestRunner)(tree),
         e2eTestRunner: options.e2eTestRunner ?? 'jest',
-        useProjectJson: options.useProjectJson ?? !(0, internal_2.isUsingTsSolutionSetup)(tree),
+        useProjectJson: options.useProjectJson ?? !isUsingTsSolutionConfig,
     };
 }
 function toNodeApplicationGeneratorOptions(options) {

package/dist/src/generators/application/schema.json

@@ -45,7 +45,7 @@
       "enum": ["none", "prettier", "oxfmt"]
     },
     "unitTestRunner": {
-      "description": "Test runner to use for unit tests.",
+      "description": "Test runner to use for unit tests. With Nest 12, which is ESM only, `jest` needs Node.js 24.9 or later, and Nx sets it up with Jest 30.5 and `--experimental-vm-modules`.",
       "type": "string",
       "enum": ["jest", "vitest", "none"],
       "default": "none",

package/dist/src/generators/init/lib/add-dependencies.js

@@ -2,10 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.addDependencies = addDependencies;
 const devkit_1 = require("@nx/devkit");
+const ensure_typescript_for_schematics_1 = require("../../../utils/ensure-typescript-for-schematics");
 const versions_1 = require("../../../utils/versions");
 function addDependencies(tree, options) {
-    return (0, devkit_1.addDependenciesToPackageJson)(tree, {}, {
+    return (0, devkit_1.runTasksInSerial)((0, devkit_1.addDependenciesToPackageJson)(tree, {}, {
         '@nestjs/schematics': (0, versions_1.versions)(tree).nestJsSchematicsVersion,
         '@nx/nest': versions_1.nxVersion,
-    }, undefined, options.keepExistingVersions ?? true);
+    }, undefined, options.keepExistingVersions ?? true), (0, ensure_typescript_for_schematics_1.ensureTypescriptForNestSchematics)(tree));
 }

package/dist/src/generators/library/lib/normalize-options.js

@@ -4,6 +4,7 @@ exports.normalizeOptions = normalizeOptions;
 exports.toJsLibraryGeneratorOptions = toJsLibraryGeneratorOptions;
 const internal_1 = require("@nx/devkit/internal");
 const internal_2 = require("@nx/js/internal");
+const unit_test_runner_1 = require("../../../utils/unit-test-runner");
 async function normalizeOptions(tree, options) {
     await (0, internal_1.ensureRootProjectName)(options, 'library');
     const { projectName, names: projectNames, projectRoot, importPath, } = await (0, internal_1.determineProjectNameAndRootOptions)(tree, {
@@ -35,7 +36,7 @@ async function normalizeOptions(tree, options) {
         service: options.service ?? false,
         target: options.target ?? 'es6',
         testEnvironment: options.testEnvironment ?? 'node',
-        unitTestRunner: options.unitTestRunner ?? 'jest',
+        unitTestRunner: options.unitTestRunner ?? (0, unit_test_runner_1.getDefaultUnitTestRunner)(tree),
         isUsingTsSolutionsConfig,
         useProjectJson: options.useProjectJson ?? !isUsingTsSolutionsConfig,
     };

package/dist/src/generators/library/library.js

@@ -8,6 +8,7 @@ const devkit_1 = require("@nx/devkit");
 const js_1 = require("@nx/js");
 const assert_supported_nestjs_version_1 = require("../../utils/assert-supported-nestjs-version");
 const assert_vitest_supported_1 = require("../../utils/assert-vitest-supported");
+const unit_test_runner_1 = require("../../utils/unit-test-runner");
 const ensure_dependencies_1 = require("../../utils/ensure-dependencies");
 const init_1 = tslib_1.__importDefault(require("../init/init"));
 const lib_1 = require("./lib");
@@ -20,6 +21,9 @@ async function libraryGenerator(tree, rawOptions) {
 async function libraryGeneratorInternal(tree, rawOptions) {
     (0, assert_supported_nestjs_version_1.assertSupportedNestJsVersion)(tree);
     const options = await (0, lib_1.normalizeOptions)(tree, rawOptions);
+    if (options.unitTestRunner === 'jest') {
+        (0, unit_test_runner_1.assertJestSupported)(tree);
+    }
     if (options.unitTestRunner === 'vitest') {
         (0, assert_vitest_supported_1.assertVitestSupported)(tree);
     }
@@ -32,6 +36,9 @@ async function libraryGeneratorInternal(tree, rawOptions) {
     (0, lib_1.addExportsToBarrelFile)(tree, options);
     (0, lib_1.updateTsConfig)(tree, options);
     (0, lib_1.addProject)(tree, options);
+    const jestTask = options.unitTestRunner === 'jest' && (0, unit_test_runner_1.usesEsmOnlyNestJs)(tree)
+        ? (0, unit_test_runner_1.configureJestForEsmOnlyNestJs)(tree, options.projectName)
+        : () => { };
     if (!options.skipFormat) {
         await (0, devkit_1.formatFiles)(tree);
     }
@@ -39,6 +46,7 @@ async function libraryGeneratorInternal(tree, rawOptions) {
         jsLibraryTask,
         initTask,
         depsTask,
+        jestTask,
         () => {
             (0, internal_1.logShowProjectCommand)(options.projectName);
         },

package/dist/src/generators/library/schema.json

@@ -34,7 +34,7 @@
       "x-priority": "important"
     },
     "unitTestRunner": {
-      "description": "Test runner to use for unit tests.",
+      "description": "Test runner to use for unit tests. With Nest 12, which is ESM only, `jest` needs Node.js 24.9 or later, and Nx sets it up with Jest 30.5 and `--experimental-vm-modules`.",
       "type": "string",
       "enum": ["jest", "vitest", "none"],
       "default": "none",

package/dist/src/migrations/update-24-1-0/ai-instructions-for-nest-12.md

@@ -0,0 +1,69 @@
+# NestJS 11 -> 12 Migration Instructions for LLM
+
+## Overview
+
+The deterministic migration bumped the declared `@nestjs/*` core packages to `^12.0.1`, bumped the declared `@nestjs/*` add-ons (such as `@nestjs/swagger`, `@nestjs/config` and `@nestjs/graphql`) to their first release that accepts NestJS 12, and, when the workspace was on TypeScript 5, upgraded `typescript` to 6 because `@nestjs/schematics` 12 requires it. NestJS 12 ships every core package as ESM only. A CommonJS app loads them through `require(esm)`, which needs Node.js 20.19+ or 22.12+ to run the app. Jest loads them only on Node.js 24.9 or later, with Jest 30.5+ and `--experimental-vm-modules`, so for each project that tests Nest code with Jest the migration upgraded `jest` to `^30.5.0` and set `NODE_OPTIONS=--experimental-vm-modules` in the `env` of the project's Jest target. The migration checked the Node.js version it ran on, `.nvmrc`, `.node-version` and `engines.node`, but it cannot see the Node.js version CI uses. This runbook covers that check and the source changes that need judgment. Do not change Nx target configuration or the webpack build setup.
+
+## Pre-Migration Checklist
+
+1. Confirm `@nestjs/core` in `package.json` resolves to 12. If it does not, the migration kept NestJS 11 on purpose; make no changes and stop.
+2. When the step's `nx_migrate_prompt` block has `impl.agentContext`, read it. It lists the packages the migration bumped and the projects that test Nest code with Jest.
+
+## Step 1: Check the Node.js version every Jest run uses
+
+Skip this step when `impl.agentContext` says no project tests Nest code with Jest.
+
+For each Jest-tested project listed in `impl.agentContext`, find every place its tests run and the Node.js version there:
+
+- CI workflow files (`.github/workflows/*.yml`, `.gitlab-ci.yml`, `azure-pipelines.yml`, `.circleci/config.yml`, `bitbucket-pipelines.yml`, `Jenkinsfile`): `node-version`, `setup-node`, container `image:` tags such as `node:22`.
+- Dockerfiles and dev container configs that run tests.
+- Version manager files the migration does not read, such as `.tool-versions` and `mise.toml`.
+
+Also check how those places run the tests. A job that sets `NODE_OPTIONS` itself, or runs `jest` directly instead of through the Nx target, does not get `--experimental-vm-modules`. Add the flag to that job's `NODE_OPTIONS` (keeping its existing value), or run the tests through `nx test`.
+
+If any of them runs these tests on a Node.js below 24.9, the bump leaves the workspace broken: the tests fail there with `SyntaxError: Unexpected token 'export'` or a "could not be executed as CommonJS" error. In that case, **revert to NestJS 11**:
+
+1. Set every `@nestjs/*` package the migration bumped back to the version it had before the migration, in `package.json` (or its catalog entry).
+2. Remove the `NODE_OPTIONS` entry the migration added to each Jest target's `env`. Leave the `jest` and `typescript` upgrades in place; both work with NestJS 11.
+3. Install, and report to the user which CI job or file runs Node.js below 24.9, and that they can move those tests to Vitest (`nx g @nx/vitest:configuration <project>`, then replace `jest.*` calls with `vi.*`) or raise that Node.js version, then re-run the migration.
+
+Stop after reverting; skip the remaining steps.
+
+If every place runs Node.js 24.9 or later, keep NestJS 12 and continue.
+
+## Step 2: Review custom pipes
+
+`ArgumentMetadata` is generic in NestJS 12. Custom pipes that implement `PipeTransform` and type the `metadata` parameter may fail to typecheck. Run typecheck on the Nest projects and fix the pipe signatures it reports.
+
+## Step 3: Review lifecycle hook ordering
+
+Lifecycle hooks (`onModuleInit`, `onApplicationBootstrap`, `onModuleDestroy`, `beforeApplicationShutdown`, `onApplicationShutdown`) now run in module hierarchy order. Search for hooks that depend on another module's hook having run first, such as a provider that reads a connection another module opens in `onModuleInit`. Do not reorder code unless such a dependency exists; report each one you find.
+
+## Step 4: Review `@Optional()` on subclasses
+
+`@Optional()` is no longer inherited by subclasses. Search for classes that extend an injectable whose constructor parameters use `@Optional()` and that do not redeclare the constructor. Add `@Optional()` to the subclass constructor where the parameter can still be missing.
+
+## Step 5: Opt-in packages
+
+Check `package.json` for each package below and follow the NestJS 12 migration guide (https://docs.nestjs.com/migration-guide) for the ones present:
+
+- `nats`: replaced by `@nats-io/transport-node`; the client options and message payloads change.
+- `subscriptions-transport-ws`: removed; use `graphql-ws`. Clients must move to the `graphql-ws` protocol too, so report it rather than changing client code.
+- `@nestjs/graphql` with `playground` config: GraphiQL is the default IDE; move `playground` options to `graphiql`.
+- `@nestjs/config` with `validationSchema`: validation uses Standard Schema; Joi needs v18+, and Joi options move under `validationOptions.libraryOptions`.
+- `@nestjs/terminus`: `HealthIndicator` and `HealthCheckError` are removed; use `HealthIndicatorService`.
+
+`ConsoleLogger` now defaults `structuredParams` to `true`, which changes log output. Do not change it; mention it to the user if the workspace parses its logs.
+
+## Post-Migration Validation
+
+1. Install dependencies. A peer dependency conflict here usually comes from an add-on the migration bumped that also raised a third-party peer, such as `@nestjs/apollo` 14 requiring `@apollo/server` 5 or `@nestjs/serve-static` 12 requiring `@fastify/static` 10. Upgrade that peer to the range the add-on asks for, and report any `@nestjs/*` package that still has no release accepting NestJS 12.
+2. Run typecheck on the Nest projects (`npx nx run-many -t typecheck -p <projects>`).
+3. Run their tests (`npx nx run-many -t test -p <projects>`). A Jest run that fails with `Unexpected token 'export'` means it runs on Node.js below 24.9 or without `--experimental-vm-modules`; go back to Step 1.
+4. Build and serve one app (`npx nx build <app>`, `npx nx serve <app>`) to confirm it starts on the workspace's Node.js.
+5. Fix failures caused by this migration and re-run until green.
+
+## Nx-Specific Notes
+
+- New Nest projects generated on NestJS 12 use Vitest by default. `--unitTestRunner=jest` works on Node.js 24.9+ and sets up Jest the same way this migration does.
+- Keep the webpack build and `@nx/js:node` serve targets as they are; a CommonJS bundle loads NestJS 12 through `require(esm)`.

package/dist/src/migrations/update-24-1-0/upgrade-to-nest-12.d.ts

@@ -0,0 +1,8 @@
+import { type Tree } from '@nx/devkit';
+type MigrationResult = {
+    nextSteps: string[];
+    agentContext: string[];
+    skipAgentic?: boolean;
+};
+export default function upgradeToNest12(tree: Tree): Promise<MigrationResult>;
+export {};

package/dist/src/migrations/update-24-1-0/upgrade-to-nest-12.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = upgradeToNest12;
+const devkit_1 = require("@nx/devkit");
+const path_1 = require("path");
+const semver_1 = require("semver");
+const ensure_typescript_for_schematics_1 = require("../../utils/ensure-typescript-for-schematics");
+const unit_test_runner_1 = require("../../utils/unit-test-runner");
+const versions_1 = require("../../utils/versions");
+// Keep these versions pinned; versions.ts advances to later majors.
+// Core packages start at 12.0.1 because 12.0.0 shipped with its peers still on ^11.
+const NEST_12_VERSIONS = {
+    '@nestjs/common': '^12.0.1',
+    '@nestjs/core': '^12.0.1',
+    '@nestjs/microservices': '^12.0.1',
+    '@nestjs/platform-express': '^12.0.1',
+    '@nestjs/platform-fastify': '^12.0.1',
+    '@nestjs/platform-socket.io': '^12.0.1',
+    '@nestjs/platform-ws': '^12.0.1',
+    '@nestjs/schematics': '^12.0.1',
+    '@nestjs/testing': '^12.0.1',
+    '@nestjs/websockets': '^12.0.1',
+    // Add-ons: the first release whose peer range accepts Nest 12.
+    '@nestjs/apollo': '^14.0.0',
+    '@nestjs/axios': '^12.0.0',
+    '@nestjs/bull': '^12.0.0',
+    '@nestjs/bullmq': '^12.0.0',
+    '@nestjs/cache-manager': '^12.0.0',
+    '@nestjs/config': '^12.0.0',
+    '@nestjs/cqrs': '^12.0.0',
+    '@nestjs/elasticsearch': '^12.0.0',
+    '@nestjs/event-emitter': '^12.0.0',
+    '@nestjs/graphql': '^14.0.0',
+    '@nestjs/jwt': '^12.0.0',
+    '@nestjs/mapped-types': '^12.0.0',
+    '@nestjs/mercurius': '^14.0.0',
+    '@nestjs/mongoose': '^12.0.0',
+    '@nestjs/passport': '^12.0.0',
+    '@nestjs/schedule': '^12.0.0',
+    '@nestjs/sequelize': '^12.0.0',
+    '@nestjs/serve-static': '^12.0.0',
+    '@nestjs/swagger': '^12.0.0',
+    '@nestjs/terminus': '^12.0.0',
+    '@nestjs/throttler': '^6.6.0',
+    '@nestjs/typeorm': '^12.0.0',
+};
+const JEST_CONFIG_FILES = [
+    'jest.config.ts',
+    'jest.config.cts',
+    'jest.config.mts',
+    'jest.config.js',
+    'jest.config.cjs',
+    'jest.config.mjs',
+];
+const SOURCE_FILE = /\.[cm]?[jt]sx?$/;
+const NEST_IMPORT = /(?:from\s+|require\(\s*|import\(\s*)['"]@nestjs\//;
+const RERUN_COMMAND = `npx nx migrate @nx/nest@${versions_1.nxVersion} --from=@nx/nest@24.0.0 --include=all && npx nx migrate --run-migration=@nx/nest:upgrade-to-nest-12`;
+async function upgradeToNest12(tree) {
+    const jestProjects = findJestTestedNestProjects(tree);
+    const oldNode = findNodeVersionsBelowJestFloor(tree);
+    if (jestProjects.length > 0 && oldNode.length > 0) {
+        return {
+            nextSteps: [
+                `Kept NestJS 11: Jest loads NestJS 12 only on Node.js ${unit_test_runner_1.jestNodeFloor} or later, and ${oldNode.join(', ')}. These projects test Nest code with Jest: ${jestProjects.join(', ')}. Move their tests to Vitest, or run them on Node.js ${unit_test_runner_1.jestNodeFloor}+, then run \`${RERUN_COMMAND}\` to move to NestJS 12.`,
+            ],
+            agentContext: [],
+            skipAgentic: true,
+        };
+    }
+    const declared = (0, devkit_1.readJson)(tree, 'package.json');
+    const bumped = Object.fromEntries(Object.entries(NEST_12_VERSIONS).filter(([name]) => declared.devDependencies?.[name] || declared.dependencies?.[name]));
+    (0, devkit_1.addDependenciesToPackageJson)(tree, {}, bumped);
+    (0, ensure_typescript_for_schematics_1.ensureTypescriptForNestSchematics)(tree);
+    for (const project of jestProjects) {
+        (0, unit_test_runner_1.configureJestForEsmOnlyNestJs)(tree, project);
+    }
+    await (0, devkit_1.formatFiles)(tree);
+    return {
+        nextSteps: [],
+        agentContext: [
+            `Bumped ${Object.entries(bumped)
+                .map(([name, version]) => `\`${name}\` to \`${version}\``)
+                .join(', ')} in package.json`,
+            jestProjects.length > 0
+                ? `These projects test Nest code with Jest, which needs Node.js ${unit_test_runner_1.jestNodeFloor}+ on NestJS 12; their Jest target now runs with NODE_OPTIONS=--experimental-vm-modules and Jest is on ^30.5.0: ${jestProjects.join(', ')}`
+                : 'No project tests Nest code with Jest',
+        ],
+    };
+}
+function findJestTestedNestProjects(tree) {
+    const projects = [];
+    for (const [name, project] of (0, devkit_1.getProjects)(tree)) {
+        const usesJest = JEST_CONFIG_FILES.some((file) => tree.exists((0, path_1.join)(project.root, file))) ||
+            Object.values(project.targets ?? {}).some((target) => target.executor === '@nx/jest:jest');
+        if (usesJest && importsNest(tree, project.root)) {
+            projects.push(name);
+        }
+    }
+    return projects.sort();
+}
+function importsNest(tree, root) {
+    let found = false;
+    (0, devkit_1.visitNotIgnoredFiles)(tree, root, (path) => {
+        if (!found && SOURCE_FILE.test(path)) {
+            found = NEST_IMPORT.test(tree.read(path, 'utf-8') ?? '');
+        }
+    });
+    return found;
+}
+// Each Node.js version the workspace can be seen to run that is below the
+// Jest floor, described for the next steps. CI configuration is left to the
+// AI instructions.
+function findNodeVersionsBelowJestFloor(tree) {
+    const found = [];
+    const current = process.versions.node;
+    if ((0, semver_1.lt)(current, unit_test_runner_1.jestNodeFloor)) {
+        found.push(`this migration runs on Node.js ${current}`);
+    }
+    // Version managers resolve a partial version like `24` to the latest match.
+    for (const file of ['.nvmrc', '.node-version']) {
+        const pinned = tree.exists(file) ? tree.read(file, 'utf-8').trim() : '';
+        if ((0, semver_1.validRange)(pinned) &&
+            !(0, semver_1.intersects)(pinned, `>=${unit_test_runner_1.jestNodeFloor}`, { includePrerelease: true })) {
+            found.push(`\`${file}\` pins Node.js ${pinned}`);
+        }
+    }
+    const engines = (0, devkit_1.readJson)(tree, 'package.json').engines?.node;
+    const enginesFloor = typeof engines === 'string' && (0, semver_1.validRange)(engines)
+        ? (0, semver_1.minVersion)(engines)
+        : null;
+    if (enginesFloor && (0, semver_1.lt)(enginesFloor, unit_test_runner_1.jestNodeFloor)) {
+        found.push(`\`engines.node\` allows Node.js ${enginesFloor.version}`);
+    }
+    return found;
+}

package/dist/src/migrations/update-24-1-0/upgrade-to-nest-12.md

@@ -0,0 +1,41 @@
+#### Upgrade NestJS 11 to 12
+
+Bumps the declared `@nestjs/*` core packages (`common`, `core`, `microservices`, `platform-*`, `schematics`, `testing`, `websockets`) to 12, and the declared add-ons such as `@nestjs/swagger`, `@nestjs/config` and `@nestjs/graphql` to their first release that accepts NestJS 12; a package manager catalog entry is bumped in the catalog. `@nestjs/schematics` 12 requires TypeScript 6, so a workspace on TypeScript 5 also gets `typescript` upgraded to the version Nx installs by default.
+
+NestJS 12 ships its core packages as ESM only. A CommonJS app loads them through `require(esm)`, which needs Node.js 20.19+ or 22.12+. Jest can load them only on Node.js 24.9 or later, with Jest 30.5+ and `--experimental-vm-modules`. For each project that tests Nest code with Jest, the migration upgrades `jest` to 30.5 and runs the project's Jest target with `NODE_OPTIONS=--experimental-vm-modules`. When the migration runs on a Node.js below 24.9, or `.nvmrc`, `.node-version` or `engines.node` allows one, the workspace stays on NestJS 11 instead, and the migration reports the projects and the command to run once their tests move to Vitest or run on Node.js 24.9+. The paired AI instructions check the Node.js version in CI, revert to NestJS 11 if a Jest run there would break, and walk through the changes that need judgment: generic `ArgumentMetadata` in custom pipes, lifecycle hook ordering, `@Optional()` on subclasses, and the opt-in NATS, GraphQL, `@nestjs/config` and Terminus changes. Read more in the [NestJS 12 migration guide](https://docs.nestjs.com/migration-guide).
+
+#### Sample Code Changes
+
+##### Before
+
+```json title="package.json"
+{
+  "dependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0"
+  },
+  "devDependencies": {
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.0",
+    "typescript": "~5.9.2"
+  }
+}
+```
+
+##### After
+
+```json title="package.json"
+{
+  "dependencies": {
+    "@nestjs/common": "^12.0.1",
+    "@nestjs/core": "^12.0.1",
+    "@nestjs/platform-express": "^12.0.1"
+  },
+  "devDependencies": {
+    "@nestjs/schematics": "^12.0.1",
+    "@nestjs/testing": "^12.0.1",
+    "typescript": "~6.0.3"
+  }
+}
+```

package/dist/src/utils/ensure-typescript-for-schematics.d.ts

@@ -0,0 +1,6 @@
+import type { GeneratorCallback, Tree } from '@nx/devkit';
+/**
+ * `@nestjs/schematics` 12 peers `typescript >=6.0.0`, and npm refuses to
+ * install it next to TypeScript 5, so the declared `typescript` is upgraded.
+ */
+export declare function ensureTypescriptForNestSchematics(tree: Tree): GeneratorCallback;

package/dist/src/utils/ensure-typescript-for-schematics.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureTypescriptForNestSchematics = ensureTypescriptForNestSchematics;
+const devkit_1 = require("@nx/devkit");
+const internal_1 = require("@nx/js/internal");
+const semver_1 = require("semver");
+/**
+ * `@nestjs/schematics` 12 peers `typescript >=6.0.0`, and npm refuses to
+ * install it next to TypeScript 5, so the declared `typescript` is upgraded.
+ */
+function ensureTypescriptForNestSchematics(tree) {
+    const schematics = (0, devkit_1.getDependencyVersionFromPackageJson)(tree, '@nestjs/schematics');
+    const schematicsMajor = schematics ? (0, semver_1.coerce)(schematics)?.major : undefined;
+    if (schematicsMajor === undefined ||
+        schematicsMajor < 12 ||
+        (0, internal_1.isTypescriptVersionAtLeast)(tree, '6.0.0')) {
+        return () => { };
+    }
+    return (0, devkit_1.addDependenciesToPackageJson)(tree, {}, { typescript: internal_1.typescriptVersion }, undefined, false);
+}

package/dist/src/utils/unit-test-runner.d.ts

@@ -0,0 +1,11 @@
+import { type GeneratorCallback, type Tree } from '@nx/devkit';
+export declare const jestNodeFloor = "24.9.0";
+export declare const jestEsmVersion = "^30.5.0";
+export declare function usesEsmOnlyNestJs(tree: Tree): boolean;
+export declare function getDefaultUnitTestRunner(tree: Tree): 'jest' | 'vitest';
+export declare function assertJestSupported(tree: Tree): void;
+/**
+ * Lets a project's Jest target load Nest 12: upgrades Jest to 30.5 and runs
+ * the target with `--experimental-vm-modules`, keeping the inferred env.
+ */
+export declare function configureJestForEsmOnlyNestJs(tree: Tree, projectName: string): GeneratorCallback;

package/dist/src/utils/unit-test-runner.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jestEsmVersion = exports.jestNodeFloor = void 0;
+exports.usesEsmOnlyNestJs = usesEsmOnlyNestJs;
+exports.getDefaultUnitTestRunner = getDefaultUnitTestRunner;
+exports.assertJestSupported = assertJestSupported;
+exports.configureJestForEsmOnlyNestJs = configureJestForEsmOnlyNestJs;
+const devkit_1 = require("@nx/devkit");
+const semver_1 = require("semver");
+const versions_1 = require("./versions");
+const firstEsmOnlyNestJsMajor = 12;
+// Jest loads the ESM-only Nest 12 packages through its require(esm) support,
+// which needs Jest 30.5, Node.js 24.9 and `--experimental-vm-modules`.
+exports.jestNodeFloor = '24.9.0';
+exports.jestEsmVersion = '^30.5.0';
+const jestNodeOptions = '--experimental-vm-modules';
+// A missing or unresolvable version (e.g. `workspace:`) falls back to the
+// latest major, like `versions()` does.
+function getNestJsMajor(tree) {
+    return (0, semver_1.major)((0, versions_1.getInstalledNestJsVersion)(tree) ?? (0, semver_1.coerce)(versions_1.nestJsVersion).version);
+}
+function usesEsmOnlyNestJs(tree) {
+    return getNestJsMajor(tree) >= firstEsmOnlyNestJsMajor;
+}
+function getDefaultUnitTestRunner(tree) {
+    return usesEsmOnlyNestJs(tree) ? 'vitest' : 'jest';
+}
+function assertJestSupported(tree) {
+    const nodeVersion = process.versions.node;
+    if (!usesEsmOnlyNestJs(tree) || !(0, semver_1.lt)(nodeVersion, exports.jestNodeFloor)) {
+        return;
+    }
+    throw new Error(`Using jest with Nest ${firstEsmOnlyNestJsMajor} requires Node.js ${exports.jestNodeFloor} or later, but this runs on Node.js ${nodeVersion}.\n` +
+        `Nest ${firstEsmOnlyNestJsMajor} is ESM only, and Jest loads it only on Node.js ${exports.jestNodeFloor}+ with ${jestNodeOptions}, which Nx sets up for you.\n` +
+        `Upgrade Node.js to ${exports.jestNodeFloor} or later, generate with "--unitTestRunner=vitest", or add "@nestjs/core@^${firstEsmOnlyNestJsMajor - 1}.0.0" to the workspace first to keep Nest ${firstEsmOnlyNestJsMajor - 1}.`);
+}
+/**
+ * Lets a project's Jest target load Nest 12: upgrades Jest to 30.5 and runs
+ * the target with `--experimental-vm-modules`, keeping the inferred env.
+ */
+function configureJestForEsmOnlyNestJs(tree, projectName) {
+    const targetName = getJestTargetName(tree);
+    const project = (0, devkit_1.readProjectConfiguration)(tree, projectName);
+    project.targets ??= {};
+    const target = (project.targets[targetName] ??= {});
+    target.options = {
+        ...target.options,
+        env: {
+            '...': true,
+            ...target.options?.env,
+            NODE_OPTIONS: jestNodeOptions,
+        },
+    };
+    (0, devkit_1.updateProjectConfiguration)(tree, projectName, project);
+    const { dependencies, devDependencies } = (0, devkit_1.readJson)(tree, 'package.json');
+    const declared = { ...dependencies, ...devDependencies };
+    return (0, devkit_1.addDependenciesToPackageJson)(tree, {}, {
+        jest: exports.jestEsmVersion,
+        ...(declared['jest-environment-node']
+            ? { 'jest-environment-node': exports.jestEsmVersion }
+            : {}),
+    }, undefined, false);
+}
+function getJestTargetName(tree) {
+    for (const plugin of (0, devkit_1.readNxJson)(tree)?.plugins ?? []) {
+        if (typeof plugin !== 'string' && plugin.plugin === '@nx/jest/plugin') {
+            return plugin.options?.targetName ?? 'test';
+        }
+    }
+    return 'test';
+}

package/dist/src/utils/versions.d.ts

@@ -2,8 +2,8 @@ import { type Tree } from '@nx/devkit';
 export declare const nxVersion: any;
 export declare const tsLibVersion = "^2.3.0";
 export declare const minSupportedNestJsVersion = "10.0.0";
-export declare const nestJsVersion = "^11.0.0";
-export declare const nestJsSchematicsVersion = "^11.0.0";
+export declare const nestJsVersion = "^12.0.0";
+export declare const nestJsSchematicsVersion = "^12.0.0";
 export declare const rxjsVersion = "^7.8.0";
 export declare const reflectMetadataVersion = "^0.2.0";
 type NestJsVersions = {

package/dist/src/utils/versions.js

@@ -9,12 +9,12 @@ const path_1 = require("path");
 exports.nxVersion = require((0, path_1.join)('@nx/nest', 'package.json')).version;
 exports.tsLibVersion = '^2.3.0';
 // NestJS has no public LTS table; cadence is roughly one major per year.
-// Support window: v10 + v11 (Rule 2 — N & N-1 — since v10.4.x still receives
-// upstream patches).
+// Support window: v11 + v12 (Rule 2 — N & N-1), with v10 kept while v10.4.x
+// still receives upstream patches.
 exports.minSupportedNestJsVersion = '10.0.0';
 // Fresh-install constants — latest supported major.
-exports.nestJsVersion = '^11.0.0';
-exports.nestJsSchematicsVersion = '^11.0.0';
+exports.nestJsVersion = '^12.0.0';
+exports.nestJsSchematicsVersion = '^12.0.0';
 exports.rxjsVersion = '^7.8.0';
 exports.reflectMetadataVersion = '^0.2.0';
 const latestVersions = {
@@ -30,6 +30,12 @@ const versionMap = {
         rxjsVersion: '^7.8.0',
         reflectMetadataVersion: '^0.1.13',
     },
+    11: {
+        nestJsVersion: '^11.0.0',
+        nestJsSchematicsVersion: '^11.0.0',
+        rxjsVersion: '^7.8.0',
+        reflectMetadataVersion: '^0.2.0',
+    },
 };
 function versions(tree) {
     const installed = getInstalledNestJsVersion(tree);

package/migrations.json

@@ -1,5 +1,17 @@
 {
-  "generators": {},
+  "generators": {
+    "upgrade-to-nest-12": {
+      "version": "24.1.0-beta.0",
+      "requires": {
+        "@nestjs/core": ">=11.0.0 <12.0.0"
+      },
+      "optionalUpdate": true,
+      "description": "Moves a NestJS 11 workspace to NestJS 12: bumps the declared `@nestjs/*` core and add-on packages, upgrades TypeScript 5 to 6 for `@nestjs/schematics` 12, and sets up Jest 30.5 with `--experimental-vm-modules` for projects that test Nest code with Jest, unless such a project runs on a Node.js below 24.9, where Jest cannot load NestJS 12; an AI prompt then checks CI and the remaining changes.",
+      "implementation": "./dist/src/migrations/update-24-1-0/upgrade-to-nest-12",
+      "prompt": "./dist/src/migrations/update-24-1-0/ai-instructions-for-nest-12.md",
+      "documentation": "./dist/src/migrations/update-24-1-0/upgrade-to-nest-12.md"
+    }
+  },
   "packageJsonUpdates": {
     "21.2.0-beta.2": {
       "version": "21.2.0-beta.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nx/nest",
-  "version": "24.0.6",
+  "version": "24.1.0-canary.20261111-edd9940",
   "private": false,
   "type": "commonjs",
   "files": [
@@ -59,16 +59,16 @@
     }
   },
   "dependencies": {
-    "@nestjs/schematics": "^11.0.0",
-    "@nx/devkit": "24.0.6",
-    "@nx/js": "24.0.6",
-    "@nx/node": "24.0.6",
+    "@nestjs/schematics": ">=11.0.0 <13.0.0",
+    "@nx/devkit": "24.1.0-canary.20261111-edd9940",
+    "@nx/js": "24.1.0-canary.20261111-edd9940",
+    "@nx/node": "24.1.0-canary.20261111-edd9940",
     "semver": "^7.6.3",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {
-    "@nestjs/core": ">=10.0.0 <12.0.0",
-    "@nestjs/common": ">=10.0.0 <12.0.0",
+    "@nestjs/core": ">=10.0.0 <13.0.0",
+    "@nestjs/common": ">=10.0.0 <13.0.0",
     "reflect-metadata": ">=0.1.0 <0.3.0",
     "rxjs": "^7.0.0"
   },