Upgrading to NestJS 12: What Changes for Existing Applications

Existing applications using class-validator and class-transformer do not need to replace their validation implementation.

For example, the traditional DTO approach continues to work:

import { IsEmail, IsNotEmpty } from 'class-validator';

export class CreateUserDto {
  @IsNotEmpty()
  name: string;

  @IsEmail()
  email: string;
}

You can continue using the existing ValidationPipe.

For applications that prefer schema-based validation, NestJS 12 provides StandardSchemaValidationPipe.

For example, a Zod schema can describe the expected request:

import { z } from 'zod';

export const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email()
});

This approach is useful when validation rules are already defined as schemas and need to be reused across different parts of an application.

Updating ConfigModule Validation

The configuration module also supports Standard Schema.

For example, an application can validate environment variables with Zod:

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { z } from 'zod';

@Module({
  imports: [
    ConfigModule.forRoot({
      validationSchema: z.object({
        NODE_ENV: z
          .enum(['development', 'production', 'test'])
          .default('development'),

        PORT: z.coerce.number().default(3000)
      })
    })
  ]
})
export class AppModule {}

This checks environment variables when the application starts.

It helps identify missing or invalid configuration before the application begins handling requests.

If your existing application uses Joi, it can continue working with Joi 18 or later. However, library-specific options previously passed directly under validationOptions must now be placed inside validationOptions.libraryOptions.

Reviewing GraphQL and Microservice Configurations

Applications using GraphQL should review their IDE configuration.

GraphiQL is now the default GraphQL IDE. The previous playground configuration has been replaced.

For example:

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  graphiql: {
    url: '/graphql',
    headers: {
      authorization: 'Bearer token'
    },
    shouldPersistHeaders: true,
    isHeadersEditorEnabled: true
  }
});

If your application uses GraphQL subscriptions, review the updated subscriptions transport configuration as well.

For NATS-based microservices, NestJS 12 introduces a package change to @nats-io/nats-core.

Applications using custom message serializers or deserializers should be checked carefully because the message handling behavior has changed.

For example, the updated package provides message headers through its own API:

import * as nats from '@nats-io/nats-core';
import { NatsRecordBuilder } from '@nestjs/microservices';

const headers = nats.headers();

headers.set('x-version', '1.0.0');

const record = new NatsRecordBuilder(payload)
  .setHeaders(headers)
  .build();

Custom deserializers should also be reviewed because they now receive the complete NATS message object rather than only a raw Uint8Array. The payload can be read using msg.json() when working with JSON messages.

Updating Custom Health Indicators

If your application uses @nestjs/terminus, check whether you have custom health indicators extending the old HealthIndicator class.

The legacy HealthIndicator and HealthCheckError APIs have been removed.

The updated approach uses HealthIndicatorService.

For example:

import { Injectable } from '@nestjs/common';
import {
  HealthIndicatorService
} from '@nestjs/terminus';

@Injectable()
export class DatabaseHealthIndicator {
  constructor(
    private readonly healthIndicatorService:
      HealthIndicatorService
  ) {}

  async check() {
    const indicator =
      this.healthIndicatorService.check('database');

    try {
      await this.checkConnection();

      return indicator.up();
    } catch {
      return indicator.down({
        message: 'Database connection failed'
      });
    }
  }

  private async checkConnection() {
    // Add the actual database connection check.
  }
}

The example shows the new indicator structure. Replace checkConnection() with your actual database connectivity check.

The important difference is that the indicator now returns an explicit healthy or unhealthy result rather than throwing the old health-check exception.

Other Changes Worth Reviewing

There are a few additional changes that can affect existing applications.

Lifecycle Hook Ordering

NestJS 12 changes lifecycle hook execution ordering across component hierarchy levels.

Review providers that depend on initialization or shutdown happening in a particular order.

Avoid relying on the order of unrelated providers unless the dependency is explicitly managed.

Optional Dependencies in Inherited Constructors

If a child class declares its own constructor, it must declare @Optional() again for an optional dependency inherited from its parent.

For example:

import {
  Injectable,
  Optional
} from '@nestjs/common';

@Injectable()
export class BaseService {
  constructor(
    @Optional() protected options?: object
  ) {}
}

@Injectable()
export class ChildService extends BaseService {
  constructor(
    @Optional() options?: object
  ) {
    super(options);
  }
}

Without the decorator in the child constructor, NestJS may treat the dependency as required.

Structured Logging

NestJS 12 changes how ConsoleLogger handles plain objects passed after a log message.

For example:

logger.log('User created', {
  userId: 101,
  email: '[email protected]'
});

The object is treated as structured parameters attached to the log entry rather than as a separate log record.

If your logging system depends on the previous behavior, review the structuredParams option.

Observability

NestJS 12 introduces the official @nestjs/observe SDK.

It provides visibility into application activity through NestJS components such as controllers, providers, GraphQL resolvers, and queue consumers.

This can help teams understand where requests spend time and investigate application failures.

It is an additional capability, not a requirement for upgrading. Existing monitoring solutions can remain in place while the team evaluates whether native NestJS instrumentation is useful.

Advantages and Disadvantages of Upgrading

The main benefit is that developers can adopt the newer framework capabilities without rebuilding their applications from scratch.

The main challenge is identifying application-specific behavior that cannot be migrated automatically.

Common Mistakes During Migration

Upgrading Only @nestjs/core

NestJS applications use several related packages. Updating only the core package can create incompatible dependency versions.

Use the upgrade command and review the complete package list.

Assuming Every Application Must Use ESM

ESM-only framework packages do not mean that every existing application must change its module system. CommonJS applications can continue working with a compatible Node.js runtime.

Ignoring Testing Framework Compatibility

Jest can load the ESM-only NestJS 12 packages only on Node.js 24.9 or later. Older supported application runtimes may therefore need a different testing setup, such as Vitest.

Skipping Integration Tests

A successful build does not prove that GraphQL, NATS, authentication, or database connections are working correctly.

Test the integrations that your application actually uses.

Deploying Without a Rollback Plan

Keep the previous working release available until the upgraded application has been verified in production.

Best Practices for a Safe Upgrade

1. Create a separate branch for the migration.

2. Verify Node.js and TypeScript compatibility.

3. Run the upgrade command with --dry-run before applying changes.

4. Upgrade related NestJS packages together.

5. Review custom GraphQL, NATS, and health-check implementations.

6. Keep the existing module system unless there is a clear reason to change it.

7. Run unit, integration, and end-to-end tests.

8. Verify environment variables and application configuration.

9. Deploy to staging before production.

10. Keep a tested rollback plan ready.

Summary

Upgrading an existing application to NestJS 12 requires attention to more than package versions. The framework introduces ESM-only packages, TypeScript 6 support, Standard Schema validation, updated CLI workflows, and changes to several integrations.

The nest upgrade command handles many mechanical migration tasks, but developers still need to review application-specific code. In particular, custom health indicators, NATS deserializers, GraphQL configuration, lifecycle hooks, and testing environments deserve attention.

Existing CommonJS applications do not need a complete ESM rewrite. Similarly, applications using class-validator can continue with their current validation approach.

The best way to approach this upgrade is to make changes in a separate branch, review the migration report, test every important integration, and verify the application in staging before production deployment.

This approach keeps the migration controlled and helps developers take advantage of NestJS 12 without introducing unnecessary changes to an existing application.