NestJS 12: ESM Packages and Observability SDK

NestJS 12 is here, and it's making waves by transitioning its core packages to ESM, introducing a native observability SDK, and enhancing schema validation. For those maintaining server-side Node.js applications with this TypeScript framework, these changes could redefine your workflow. Let's dive into what this means for your codebase.

What Changed in NestJS 12?

The most notable update in NestJS 12 is the shift of its core packages to ECMAScript Modules (ESM). This transition means that, while the framework still supports CommonJS applications, future projects will default to ESM, with the option to choose between Vitest and oxlint for testing and linting. The monorepo bundler is also now Rspack, replacing webpack.

This shift to ESM requires Node.js 20.19+ or 22.12+. While the move to ESM doesn't bring immediate performance improvements—developer Anton Chapala's benchmarks showed no significant startup or memory gains—it does clean up tooling and configuration, streamlining the development process. Chapala's conclusion that this change is a "massive cleanup of tooling and configuration debt" underscores the potential for long-term maintenance benefits.

In practical terms, when creating a new NestJS application using the CLI, developers are now prompted to choose between a CommonJS or ESM project. This decision affects not only module syntax but also the default tools bundled with the project, such as testing frameworks and linters. For teams already set in their ways with CommonJS, the choice allows for a gradual transition without immediate disruption.

Schema Validation Gets an Upgrade

Another significant change is in schema validation. NestJS 12 introduces first-class support for Standard Schema validation, allowing route decorators like @Body(), @Query(), and @Param() to directly accept schemas from libraries like Zod, Valibot, and ArkType without third-party wrappers. This enhancement reduces boilerplate code and gives developers more flexibility in selecting their validation libraries.

However, for those using class-validator, it's still the documented default. Building on a specification rather than directly on Zod keeps the selection in developers' hands, as highlighted by blogger iiaku. Yet, types still need manual annotation due to Nest's reliance on legacy TypeScript decorators. This manual annotation requirement can be a significant overhead, especially in large-scale applications where type safety is a priority. The need to manually annotate types can slow down development and introduce human error, which is something teams need to manage carefully.

The New Observability SDK

NestJS 12's observability enhancements come with the introduction of the @nestjs/observe package. This SDK integrates into NestJS's lifecycle, allowing for reporting traces in terms of controllers and providers rather than patching the HTTP server directly. While this offers a richer context for application performance monitoring, it is not without its caveats.

Scout Monitoring has pointed out that this SDK is NestJS-specific, lacking cross-stack correlation out of the box, which could lead to potential vendor lock-in. This is something to be cautious about if your stack involves other frameworks or libraries. The SDK's focus on NestJS may limit its applicability in heterogeneous environments where multiple technologies are in use.

Additionally, the new nest deploy command, which forwards to the Mau platform, suggests a push towards integrating first-party services, which could further entrench users in the NestJS ecosystem. While this might simplify deployment for some, it could also limit flexibility for those who prefer or require different deployment solutions.

Upgrading to NestJS 12

If you're considering upgrading from NestJS 11, the process is relatively straightforward. Start by installing the latest CLI with:

npm i -g @nestjs/cli@latest

Then, run the upgrade command:

nest upgrade

This will update all @nestjs/* packages to version 12, bump your TypeScript version to 6, and make other mechanical updates like switching from GraphQL Playground to GraphiQL and updating the NATS client.

Importantly, the upgrade process doesn't automatically convert your project to ESM, Vitest, or oxlint. You'll need to manually make those changes if you wish to take advantage of the new default configurations. The migration guide provided by NestJS covers additional changes, including lifecycle hook ordering and the upgrade to Joi v18. It's crucial to follow the guide closely to ensure a smooth transition.

One specific issue to be aware of is the requirement for AWS Lambda runtimes to use the --experimental-require-module flag, a point noted in the documentation following a GitHub issue report. This is critical for developers deploying applications on AWS, as failing to include this flag could lead to runtime errors.

Real-World Implications

For developers like myself, working in environments such as newsroom CMSs or AI-assisted content workflows—aspects like observability and schema validation are crucial. The enhanced schema validation can significantly streamline API development, especially when dealing with complex validation scenarios. Meanwhile, the observability SDK is something I'd test extensively in environments where monitoring and performance metrics are vital, such as in Next.js security updates or Node.js crypto enhancements.

However, my concern lies in the potential for vendor lock-in with the observability SDK. It's essential to weigh the benefits of richer context against the limitations of NestJS-only support. For projects that rely on multi-stack integrations, this might be a dealbreaker.

What This Does Not Solve

While NestJS 12 introduces several exciting features, there are aspects it doesn't address. For instance, the reliance on legacy TypeScript decorators means manual type annotations remain necessary. This can become cumbersome in larger projects where type safety is critical.

Additionally, the transition to ESM could introduce compatibility issues, particularly with AWS Lambda runtimes, which require the --experimental-require-module flag. Path aliases breaking under ESM and Fastify middleware exceptions are other issues reported by users. These might necessitate workarounds or adjustments in your codebase. The community has noted these issues, and it's important to stay updated with any patches or workarounds provided by the NestJS team.

Overall, NestJS 12 is a substantial update that offers both opportunities and challenges. If your project can benefit from the new schema validation and observability features, it's worth exploring. However, be prepared to address the potential pitfalls, especially regarding ESM compatibility and observability integration. In my experience, keeping abreast of community discussions and updates can mitigate some of these challenges, ensuring your NestJS applications remain robust and up-to-date.