Vai al contenuto
verdict:

NestJS 12.0.0

featured

Note di rilascio

note: la sintesi e le note di rilascio sono in inglese

warning: intervento richiesto

9 breaking changes5 punti chiave

NestJS 12 brings ESM packages, Standard Schema support and a rebuilt CLI, and requires Node.js v20.19+ or v22.12+.

sintesi · solo dalle note di rilascio · claude-haiku-5-5 · prompt v7

breaking changestutte citate, ognuna con una soluzione

breaking[1]: The nats package is replaced by @nats-io/transport-node, and packets are serialized as JSON strings.

release-notes:174
| **NATS v3** — the nats package is replaced by @nats-io/transport-node | npm uninstall nats && npm install @nats-io/transport-node; update direct imports. Packets are now serialized as JSON strings and custom deserializers receive the full NATS message — read payloads with msg.json(). |

help: Run npm uninstall nats && npm install @nats-io/transport-node, update direct imports, and read payloads with msg.json().

breaking[2]: GraphQL subscriptions no longer support subscriptions-transport-ws, and the protocols are wire-incompatible.

release-notes:175
| **GraphQL subscriptions** — subscriptions-transport-ws support removed | Switch to graphql-ws; the protocols are wire-incompatible, so clients must be updated. Review onConnect callbacks. |

help: Switch to graphql-ws, update clients to match, and review onConnect callbacks.

breaking[3]: GraphiQL becomes the default GraphQL IDE in place of playground.

release-notes:176
| **GraphiQL** is the default GraphQL IDE | Replace playground with graphiql; pass an options object to customize. |

help: Replace playground with graphiql, and pass an options object to customize it.

breaking[4]: Lifecycle hooks are now invoked by component hierarchy level.

release-notes:173
| **Lifecycle hooks** are now invoked by component hierarchy level | Review ordering assumptions between related providers/modules in init, teardown, and tests. |

help: Review ordering assumptions between related providers and modules in init, teardown and tests.

breaking[5]: Node.js versions older than v20.19 or v22.12, including the 21.x line, are no longer supported.

release-notes:29
**Node.js:** v12 requires **Node.js v20.19+ or v22.12+**. Both require(esm) and the ESM packages depend on it; the upgrade command refuses to run on older releases (including the 21.x line). The latest active LTS is recommended.

help: Upgrade Node.js to v20.19+ or v22.12+ before upgrading NestJS.

breaking[6]: @nestjs/config validates through Standard Schema, and Joi-specific settings move.

release-notes:107
Existing Joi schemas still work with two caveats: upgrade to **Joi v18+** (the first release implementing Standard Schema), and move library-specific settings under validationOptions.libraryOptions.

help: Upgrade to Joi v18+ and move library-specific settings under validationOptions.libraryOptions.

breaking[7]: Pipe transform signatures are refined and ArgumentMetadata is now generic.

release-notes:178
| **Pipe transform signatures** refined; ArgumentMetadata is now generic | Adjust hand-written custom pipe signatures if the compiler complains. |

help: Adjust hand-written custom pipe signatures if the compiler complains.

breaking[8]: ConsoleLogger structured params are on by default, which changes log output.

release-notes:138
In JSON mode they nest under params, or spread into the root with flattenParams. On by default; set structuredParams: false to restore the old behavior.

help: Set structuredParams: false to restore the previous output.

breaking[9]: The angular schematic has been removed.

release-notes:157
The decorator schematic generates decorators using the preferred Reflector.createDecorator() form. The angular schematic has been **removed**.

help: The notes give no migration; check your scripts and workflows for uses of the angular schematic.

punti chiave

release-notesgithub.com/nestjs/nest · 204 righe
  1. # NestJS v12.0.0
  3. NestJS 12 is centered around **ESM-ready packages**, **first-class [Standard Schema](https://standardschema.dev/) support** for validation and serialization, a **rebuilt CLI**, and **native observability** through the new `@nestjs/observe` SDK.
  5. Existing CommonJS applications keep working — migrating your own code to ESM is entirely optional.
  7. 📖 Full [migration guide](https://docs.nestjs.com/migration-guide)
  9. ---
  11. ## Upgrading
  13. Upgrade the CLI first, since the upgrade command ships with it:
  15. ```bash
  16. npm i -g @nestjs/cli@latest
  17. ```
  19. Then, from the root of your project:
  21. ```bash
  22. nest upgrade
  23. ```
  25. `nest upgrade` moves every `@nestjs/*` package to its v12-compatible major at once and applies the mechanical parts of the migration for you — `nest-cli.json` webpack options, the GraphQL `playground` → `graphiql` rename and subscriptions transport swap, the NATS package replacement, `@nestjs/config` validation options, Jest and Joi bumps — then prints a report of everything it changed and everything you still need to review by hand. Run it with `--dry-run` first to see that report without touching your files.
  27. It deliberately does **not** migrate your project to ESM, Vitest, or oxlint. Those are the defaults for newly generated projects; existing projects adopt them on their own schedule.
  29. **Node.js:** v12 requires **Node.js v20.19+ or v22.12+**. Both `require(esm)` and the ESM packages depend on it; the upgrade command refuses to run on older releases (including the 21.x line). The latest active LTS is recommended.
  31. ---
  33. ## Highlights
  35. ### ESM packages
  37. All core Nest packages now ship as ESM. Thanks to `require(esm)` in modern Node.js, most existing CommonJS applications continue to work without a rewrite. Review custom bootstrapping scripts, build tooling, and test runners if they assume CommonJS-only packages.
  39. `nest new` now asks whether to scaffold a **CommonJS** or an **ESM** project.
  41. ### Standard Schema validation
  43. Route parameter decorators — `@Body()`, `@Query()`, `@Param()`, `@RawBody()` — accept a new `schema` option, designed for Standard Schema compatible libraries such as Zod, Valibot, and ArkType:
  45. ```ts
  46. @Post()
  47. create(@Body({ schema: createUserSchema }) body: CreateUserDto) {
  48. return this.usersService.create(body);
  49. }
  51. @Get(':id')
  52. findOne(@Param('id', { schema: z.coerce.number().int().positive() }) id: number) {
  53. return this.usersService.findOne(id);
  54. }
  55. ```
  57. The decorator only attaches metadata; register the new `StandardSchemaValidationPipe` to validate against it:
  59. ```ts
  60. app.useGlobalPipes(new StandardSchemaValidationPipe());
  61. ```
  63. The same schemas feed OpenAPI generation. The decorator-based `class-validator` workflow remains fully supported, with no plan to remove it.
  65. ### Standard Schema serialization
  67. `StandardSchemaSerializerInterceptor` validates and transforms outgoing responses with the same ecosystem:
  69. ```ts
  70. @UseInterceptors(StandardSchemaSerializerInterceptor)
  71. @SerializeOptions({ schema: userResponseSchema })
  72. @Get(':id')
  73. findOne(@Param('id') id: string) {
  74. return this.usersService.findOne(id);
  75. }
  76. ```
  78. Pick per use case: `ValidationPipe` / `ClassSerializerInterceptor` for class-based DTOs, the Standard Schema variants when your schemas already exist.
  80. ### Native observability — `@nestjs/observe`
  82. The official [NestJS Observe](https://observe.nestjs.com) SDK plugs into Nest's own request lifecycle through the `instrument` application option, rather than patching the HTTP server like a generic APM agent. Requests, jobs, errors, and traces are reported in terms of your controllers, providers, resolvers, and queue consumers:
  84. ```ts
  85. export const { ObserveModule, ObserveInstrument } = createObserveModule();
  87. const app = await NestFactory.create(AppModule, {
  88. instrument: ObserveInstrument,
  89. });
  90. ```
  92. Auto-instrumentation covers HTTP, GraphQL, gRPC, and microservice transports, plus queue consumers and cron runs — no manual span wiring and no collector to run. Opt-in and new; nothing to migrate. `nest new` and `nest upgrade` can wire it up for you (`--observe`). See the [Observability chapter](https://docs.nestjs.com/observability/overview).
  94. ### Config module on Standard Schema
  96. `@nestjs/config` moves from Joi-specific validation to Standard Schema. `validationSchema` now accepts any compatible schema:
  98. ```ts
  99. ConfigModule.forRoot({
  100. validationSchema: z.object({
  101. NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  102. PORT: z.coerce.number().default(3000),
  103. }),
  104. });
  105. ```
  107. Existing Joi schemas still work with two caveats: upgrade to **Joi v18+** (the first release implementing Standard Schema), and move library-specific settings under `validationOptions.libraryOptions`.
  109. ### Route conflict diagnostics
  111. Routes are registered in declaration order, so on order-sensitive adapters `@Get(':id')` can silently shadow a `@Get('me')` declared after it. Two **opt-in** options surface this:
  113. ```ts
  114. const app = await NestFactory.create(AppModule, {
  115. routeConflictPolicy: { duplicate: 'error', shadow: 'warn' },
  116. routeResolutionStrategy: 'specificity',
  117. });
  118. ```
  120. Both default to the previous behavior, so nothing changes unless you set them.
  122. ### Machine-readable error codes
  124. `HttpExceptionOptions` accepts an `errorCode` that is serialized into the response body, so clients branch on a stable identifier instead of parsing message strings:
  126. ```ts
  127. throw new BadRequestException('Password is too weak', { errorCode: 'WEAK_PASSWORD' });
  128. ```
  130. ### Structured logging params
  132. `ConsoleLogger` now treats plain objects passed after the message as structured params of the same log entry instead of separate records:
  134. ```ts
  135. logger.log('User created', { userId: 1, email: 'foo@bar.com' });
  136. ```
  138. In JSON mode they nest under `params`, or spread into the root with `flattenParams`. On by default; set `structuredParams: false` to restore the old behavior.
  140. ---
  142. ## CLI (`@nestjs/cli` v12)
  144. The CLI was rebuilt in [nestjs/nest-cli#3280](https://github.com/nestjs/nest-cli/pull/3280): the entire source migrated to ESM, tests moved from Jest to Vitest, e2e tests were added for every command, and command classes were refactored to take typed context objects instead of untyped inputs and option arrays.
  146. **New commands**
  148. - **`nest upgrade`** (alias `update`) — upgrades a v11 project to v12 and applies the migration steps described above.
  149. - **`nest deploy`** — deploys your application to the cloud via [Mau](https://mau.nestjs.com/), installing `@nestjs/mau` on first use and forwarding every argument straight through.
  151. **Defaults and tooling**
  153. - **Rspack** is the new default bundler for monorepos. The `--webpack` / `--webpackPath` flags (and their `webpack` / `webpackConfigPath` counterparts in `nest-cli.json`) are **deprecated** in favor of `--builder rspack`.
  154. - **oxlint** replaces ESLint in generated projects.
  155. - **Vitest** is the default test runner for ESM projects; CommonJS projects continue with Jest.
  156. - **bun** is now a supported package manager, alongside npm, yarn, and pnpm.
  157. - The `decorator` schematic generates decorators using the preferred `Reflector.createDecorator()` form. The `angular` schematic has been **removed**.
  159. **New options**
  161. - `nest build` / `nest start`: `--rspackPath [path]`, `--emit-declarations` (SWC), `--no-type-check`, `--silent`
  162. - `nest build`: `--parallel [concurrency]`, for building monorepo projects in parallel with `--all`
  163. - `nest-cli.json`: `includeLibraryAssets`, for copying library assets into an application build
  165. ---
  167. ## Breaking changes
  169. | Change | What to do |
  170. | --- | --- |
  171. | Packages ship as **ESM** | Usually nothing — `require(esm)` keeps CommonJS apps working. Review custom bootstrapping, bundler, and test-runner config. |
  172. | **Node.js v20.19+ / v22.12+** required | Upgrade Node; the 21.x line is not supported. |
  173. | **Lifecycle hooks** are now invoked by component hierarchy level | Review ordering assumptions between related providers/modules in init, teardown, and tests. |
  174. | **NATS v3** — the `nats` package is replaced by `@nats-io/transport-node` | `npm uninstall nats && npm install @nats-io/transport-node`; update direct imports. Packets are now serialized as JSON strings and custom deserializers receive the full NATS message — read payloads with `msg.json()`. |
  175. | **GraphQL subscriptions** — `subscriptions-transport-ws` support removed | Switch to `graphql-ws`; the protocols are wire-incompatible, so clients must be updated. Review `onConnect` callbacks. |
  176. | **GraphiQL** is the default GraphQL IDE | Replace `playground` with `graphiql`; pass an options object to customize. |
  177. | **`@nestjs/config`** validates through Standard Schema | Keep Joi by upgrading to v18+ and moving library settings under `validationOptions.libraryOptions`. |
  178. | **Pipe transform signatures** refined; `ArgumentMetadata` is now generic | Adjust hand-written custom pipe signatures if the compiler complains. |
  179. | **`ConsoleLogger` structured params** on by default | Set `structuredParams: false` to restore the previous output. |
  180. | **Webpack CLI workflows** deprecated | Migrate to `--builder rspack`. |
  181. | **`angular` schematic** removed | — |
  183. Most of these are handled automatically by `nest upgrade`.
  185. ---
  187. ## Also in this release
  189. - **`ValidationPipe` error format** — a new option controls the shape of validation error responses.
  190. - **gRPC exception filter** — `GrpcExceptionFilter` and status-specific exceptions map errors to proper gRPC status codes instead of `UNKNOWN`.
  191. - **Regex Kafka patterns** — `@MessagePattern()` and `@EventPattern()` accept a `RegExp` on the Kafka transport.
  192. - **Request-scoped WebSocket gateways** — gateways support request-scoped providers, with the socket injectable via the `REQUEST` token.
  193. - **WebSocket disconnect reason** — `handleDisconnect` can receive the reason for the disconnection.
  194. - **Microservices pre-request hook** — a new hook runs before a message handler is invoked.
  195. - **Express graceful shutdown** — the Express adapter drains in-flight requests on shutdown.
  196. - **HTTP adapter error mapping** — reworked across core, Express, and Fastify adapters.
  198. ---
  200. ## Thanks
  202. Thank you to everyone who contributed code, issues, reproductions, and reviews to this release. 💛
  204. If NestJS helps you build your products, consider [supporting the project](https://docs.nestjs.com/support).

vedi su githubimported 2026-09-28 via npm