Migration guide

This article provides a set of guidelines for migrating from Nest version 6 to version 7.

Custom route decorators

The Custom decorators API has been unified for all types of applications. Now, whether you’re creating a GraphQL application or a REST API, the factory passed into the createParamDecorator() function will take the ExecutionContext (read more here) object as a second argument.

  2. // Before
  3. import { createParamDecorator } from '@nestjs/common';
  5. export const User = createParamDecorator((data, req) => {
  6.   return req.user;
  7. });
  9. // After
  10. import { createParamDecorator, ExecutionContext } from '@nestjs/common';
  12. export const User = createParamDecorator(
  13.   (data: unknown, ctx: ExecutionContext) => {
  14.     const request = ctx.switchToHttp().getRequest();
  15.     return request.user;
  16.   },
  17. );
  2. // Before
  3. import { createParamDecorator } from '@nestjs/common';
  5. export const User = createParamDecorator((data, req) => {
  6.   return req.user;
  7. });
  9. // After
  10. import { createParamDecorator } from '@nestjs/common';
  12. export const User = createParamDecorator((data, ctx) => {
  13.   const request = ctx.switchToHttp().getRequest();
  14.   return request.user;
  15. });

Microservices

To avoid code duplication, the MicroserviceOptions interface has been removed from the @nestjs/common package. Therefore, now when you’re creating a microservice (through either createMicroservice() or connectMicroservice() method), you should pass the type generic parameter to get code autocompletion.

  2. // Before
  3. const app = await NestFactory.createMicroservice(AppModule);
  5. // After
  6. const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule);
  2. // Before
  3. const app = await NestFactory.createMicroservice(AppModule);
  5. // After
  6. const app = await NestFactory.createMicroservice(AppModule);

Hint The MicroserviceOptions interface is exported from the @nestjs/microservices package.

GraphQL

In the version 6 major release of NestJS, we introduced the code-first approach as a compatibility layer between the type-graphql package and the @nestjs/graphql module. Eventually, our team decided to reimplement all the features from scratch due to a lack of flexibility. To avoid numerous breaking changes, the public API is backward-compatible and may resemble type-graphql.

In order to migrate your existing application, simply rename all the type-graphql imports to the @nestjs/graphql. If you used more advanced features, you might need to also:

  • use Type (imported from @nestjs/common) instead of ClassType (imported from type-graphql)
  • move methods that require @Args() from object types (classes annotated with @ObjectType() decorator) under resolver classes (and use @ResolveField() decorator instead of @Field())

Terminus

In the version 7 major release of @nestjs/terminus, a new simplified API has been introduced to run health checks. The previously required peer dependency @godaddy/terminus has been removed, which allows us to integrate our health checks automatically into Swagger! Read more about the removal of @godaddy/terminushere.

For most users, the biggest change will be the removal of the TerminusModule.forRootAsync function. With the next major version, this function will be completely removed. To migrate to the new API, you will need to create a new controller, which will handle your health checks.

  2. // Before
  3. @Injectable()
  4. export class TerminusOptionsService implements TerminusOptionsFactory {
  5.   constructor(
  6.     private dns: DNSHealthIndicator,
  7.   ) {}
  9.   createTerminusOptions(): TerminusModuleOptions {
  10.     const healthEndpoint: TerminusEndpoint = {
  11.       url: '/health',
  12.       healthIndicators: [
  13.         async () => this.dns.pingCheck('google', 'https://google.com'),
  14.       ],
  15.     };
  16.     return {
  17.       endpoints: [healthEndpoint],
  18.     };
  19.   }
  20. }
  22. @Module({
  23.   imports: [
  24.     TerminusModule.forRootAsync({
  25.       useClass: TerminusOptionsService
  26.     })
  27.   ]
  28. })
  29. export class AppModule { }
  31. // After
  32. @Controller('health')
  33. export class HealthController {
  34.   constructor(
  35.     private health: HealthCheckService,
  36.     private dns: DNSHealthIndicator,
  37.   ) { }
  39.   @Get()
  40.   @HealthCheck()
  41.   healthCheck() {
  42.     return this.health.check([
  43.       async () => this.dns.pingCheck('google', 'https://google.com'),
  44.     ]);
  45.   }
  46. }
  48. @Module({
  49.   imports: [
  50.     TerminusModule
  51.   ]
  52. })
  53. export class AppModule { }
  2. // Before
  3. @Injectable()
  4. @Dependencies(DNSHealthIndicator)
  5. export class TerminusOptionsService {
  6.   constructor(
  7.     private dns,
  8.   ) {}
  10.   createTerminusOptions() {
  11.     const healthEndpoint = {
  12.       url: '/health',
  13.       healthIndicators: [
  14.         async () => this.dns.pingCheck('google', 'https://google.com'),
  15.       ],
  16.     };
  17.     return {
  18.       endpoints: [healthEndpoint],
  19.     };
  20.   }
  21. }
  23. @Module({
  24.   imports: [
  25.     TerminusModule.forRootAsync({
  26.       useClass: TerminusOptionsService
  27.     })
  28.   ]
  29. })
  30. export class AppModule { }
  32. // After
  33. @Controller('/health')
  34. @Dependencies(HealthCheckService, DNSHealthIndicator)
  35. export class HealthController {
  36.   constructor(
  37.     private health,
  38.     private dns,
  39.   ) { }
  41.   @Get('/')
  42.   @HealthCheck()
  43.   healthCheck() {
  44.     return this.health.check([
  45.       async () => this.dns.pingCheck('google', 'https://google.com'),
  46.     ])
  47.   }
  48. }
  50. @Module({
  51.   controllers: [
  52.     HealthController
  53.   ],
  54.   imports: [
  55.     TerminusModule
  56.   ]
  57. })
  58. export class AppModule { }

Warning If you have set a Global Prefix in your Nest application and you have not used the useGlobalPrefix Terminus option, the URL of your health check will change. Make sure to update the reference to that URL, or use the legacy Terminus API until nestjs/nest#963 is fixed.

If you are forced to use the legacy API, you can also disable deprecation messages for the time being.

  2. TerminusModule.forRootAsync({
  3.   useFactory: () => ({
  4.     disableDeprecationWarnings: true,
  5.     endpoints: [
  6.       // ...
  7.     ]
  8.   })
  9. }

You should enable shutdown hooks in your main.ts file. The Terminus integration will listen on POSIX signals such as SIGTERM (see the Application shutdown chapter for more information). When enabled, the health check route(s) will automatically respond with a Service Unavailable (503) HTTP error response when the server is shutting down.

With the removal of @godaddy/terminus, you will need to update your import statements to use @nestjs/terminus instead. Most notable is the import of the HealthCheckError.

custom.health.ts

  2. // Before
  3. import { HealthCheckError } from '@godaddy/terminus';
  4. // After
  5. import { HealthCheckError } from '@nestjs/terminus';

Once you have fully migrated, make sure you uninstall @godaddy/terminus.

  2. npm uninstall --save @godaddy/terminus

HTTP exceptions body

Previously, the generated response bodies for the HttpException class and other exceptions derived from it (e.g., BadRequestException or NotFoundException) were inconsistent. In the latest major release, these exception responses will follow the same structure.

  2. /*
  3.  * Sample outputs for "throw new ForbiddenException('Forbidden resource')"
  4.  */
  6. // Before
  7. {
  8.   "statusCode": 403,
  9.   "message": "Forbidden resource"
  10. }
  12. // After
  13. {
  14.   "statusCode": 403,
  15.   "message": "Forbidden resource",
  16.   "error": "Forbidden"
  17. }

Validation errors schema

In past releases, the ValidationPipe threw an array of the ValidationError objects returned by the class-validator package. Now, ValidationPipe will map errors to a list of plain strings representing error messages.

  2. // Before
  3. {
  4.   "statusCode": 400,
  5.   "error": "Bad Request",
  6.   "message": [
  7.     {
  8.       "target": {},
  9.       "property": "email",
  10.       "children": [],
  11.       "constraints": {
  12.         "isEmail": "email must be an email"
  13.       }
  14.     }
  15.   ]
  16. }
  18. // After
  19. {
  20.   "statusCode": 400,
  21.   "message": ["email must be an email"],
  22.   "error": "Bad Request"
  23. }

If you prefer the previous approach, you can restore it by setting the exceptionFactory function:

  2. new ValidationPipe({
  3.   exceptionFactory: (errors) => new BadRequestException(errors),
  4. });

Implicit type conversion (ValidationPipe)

With the auto-transformation option enabled (transform: true), the ValidationPipe will now perform conversion of primitive types. In the following example, the findOne() method takes one argument which represents an extracted id path parameter:

  2. @Get(':id')
  3. findOne(@Param('id') id: number) {
  4.   console.log(typeof id === 'number'); // true
  5.   return 'This action returns a user';
  6. }

By default, every path parameter and query parameter comes over the network as a string. In the above example, we specified the id type as a number (in the method signature). Therefore, the ValidationPipe will try to automatically convert a string identifier to a number.

Microservice channels (bidirectional communication)

To enable the request-response message type, Nest creates two logical channels - one is responsible for transferring the data while the other waits for incoming responses. For some underlying transports, such as NATS, this dual-channel support is provided out-of-the-box. For others, Nest compensates by manually creating separate channels.

Let’s say that we have a single message handler @MessagePattern('getUsers'). In the past, Nest built two channels from this pattern: getUsers_ack (for requests) and getUsers_res (for responses). With version 7, this naming scheme changes. Now Nest will build getUsers (for requests) and getUsers.reply (for responses) instead. Also, specifically for the MQTT transport strategy, the response channel would be getUsers/reply (to avoid conflicts with topic wildcards).

Deprecations

All deprecations (from Nest version 5 to version 6) have been finally removed (e.g., the deprecated @ReflectMetadata decorator).

Node.js

This release drops support for Node v8. We strongly recommend using the latest LTS version.