nestjs-zod

✨ A seamless validation solution for your NestJS application ✨
by @benlorantfy

Core Library Features

✨ Create nestjs DTOs from zod schemas

✨ Validate / parse request body, query params, and url params using zod

✨ Serialize response bodies using zod

✨ Automatically generate OpenAPI documentation using zod

✨ Supports zod codecs

Sponsored by: apisandbox.dev

Getting Started

Automatic Setup

nestjs-zod can be automatically setup by running the following command:

npx nestjs-zod-cli /path/to/nestjs/project

This command runs a codemod that adds the validation pipe, serialization interceptor, http exception filter, and swagger cleanup function

Alternatively, you can follow the manual setup steps below

Manual Setup

1. Install the package:

    npm install nestjs-zod # Note: zod ^3.25.0 || ^4.0.0 is also required

2. Add ZodValidationPipe to the AppModule

   Show me how

   ZodValidationPipe is required in order to validate the request body, query, and params

    + import { APP_PIPE } from '@nestjs/core';
    + import { ZodValidationPipe } from 'nestjs-zod';
   
    @Module({
      imports: [],
      controllers: [AppController],
      providers: [
    +    {
    +      provide: APP_PIPE,
    +      useClass: ZodValidationPipe,
    +    },
      ]
    })
    export class AppModule {}

3. Add ZodSerializerInterceptor to the AppModule

   Show me how

   ZodSerializerInterceptor is required in order to validate the response bodies

    - import { APP_PIPE } from '@nestjs/core';
    + import { APP_PIPE, APP_INTERCEPTOR } from '@nestjs/core';
    - import { ZodValidationPipe } from 'nestjs-zod';
    + import { ZodValidationPipe, ZodSerializerInterceptor } from 'nestjs-zod';
   
    @Module({
      imports: [],
      controllers: [AppController],
      providers: [
        {
          provide: APP_PIPE,
          useClass: ZodValidationPipe,
        },
    +    {
    +      provide: APP_INTERCEPTOR,
    +      useClass: ZodSerializerInterceptor,
    +    },
      ]
    })
    export class AppModule {}

4. [OPTIONAL] Add an HttpExceptionFilter

   Show me how

   An HttpExceptionFilter is required in order to add custom handling for zod errors

    - import { APP_PIPE, APP_INTERCEPTOR } from '@nestjs/core';
    + import { APP_PIPE, APP_INTERCEPTOR, APP_FILTER } from '@nestjs/core';
    import { ZodValidationPipe, ZodSerializerInterceptor } from 'nestjs-zod';
    + import { HttpExceptionFilter } from './http-exception.filter';
   
    @Module({
      imports: [],
      controllers: [AppController],
      providers: [
        {
          provide: APP_PIPE,
          useClass: ZodValidationPipe,
        },
        {
          provide: APP_INTERCEPTOR,
          useClass: ZodSerializerInterceptor,
        },
        {
          provide: APP_FILTER,
          useClass: HttpExceptionFilter,
        }
      ]
    })
    export class AppModule {}
   
    + // http-exception.filter
    + @Catch(HttpException)
    + export class HttpExceptionFilter extends BaseExceptionFilter {
    +     private readonly logger = new Logger(HttpExceptionFilter.name);
    + 
    +     catch(exception: HttpException, host: ArgumentsHost) {
    +         if (exception instanceof ZodSerializationException) {
    +             const zodError = exception.getZodError();
    +             if (zodError instanceof ZodError) {
    +                 this.logger.error(`ZodSerializationException: ${zodError.message}`);
    +             }
    +         }
    + 
    +         super.catch(exception, host);
    +     }
    + }

5. [OPTIONAL] Add cleanupOpenApiDoc

   Important: This step is important if using @nestjs/swagger

   Show me how

   cleanupOpenApiDoc is required if using @nestjs/swagger to properly post-process the OpenAPI doc

    - SwaggerModule.setup('api', app, openApiDoc);
    + SwaggerModule.setup('api', app, cleanupOpenApiDoc(openApiDoc));

Check out the example app for a full example of how to integrate nestjs-zod in your nestjs application

Documentation

• Request Validation
  • createZodDto (Create a DTO from a Zod schema)
  • ZodValidationPipe (Get nestjs to validate using zod)
  • createZodValidationPipe (Creating custom validation pipe)
  • ZodValidationException
  • ZodSchemaDeclarationException
• Response Validation
  • ZodSerializerDto (Set zod DTO to serialize responses with)
  • ZodSerializerInterceptor (Get nestjs to serialize responses with zod)
  • createZodSerializerInterceptor (Creating custom serializer interceptor)
  • ZodResponse (Sync run-time, compile-time, and docs-time schemas)
  • ZodSerializationException
• OpenAPI (Swagger) support
  • cleanupOpenApiDoc (Ensure proper OpenAPI output)
  • Output schemas
  • Codecs
  • Reusable schemas
  • zodV3ToOpenAPI (⚠️ DEPRECATED)
• validate (⚠️ DEPRECATED)
• ZodGuard (⚠️ DEPRECATED)
  • createZodGuard (Creating custom guard)
• @nest-zod/z (⚠️ DEPRECATED)
  • ZodDateString
  • ZodPassword

Request Validation

createZodDto (Create a DTO from a Zod schema)

function createZodDto<TSchema extends UnknownSchema, TCodec extends boolean = false>(schema: TSchema, options?: { codec: TCodec }): ZodDto<TSchema, TCodec>;

Creates a nestjs DTO from a zod schema. These zod DTOs can be used in place of class-validator / class-transformer DTOs. Zod DTOs are responsible for three things:

1. Providing a schema for ZodValidationPipe to validate incoming client data against
2. Providing a compile-time typescript type from the Zod schema
3. Providing an OpenAPI schema when using nestjs/swagger

[!NOTE] For this feature to work, please ensure ZodValidationPipe is setup correctly

Parameters

• schema - A zod schema. You can "bring your own zod", including zod v3 schemas, v4 schemas, zod mini schemas, etc. The only requirement is that the schema has a method called parse
• options
  • options.codec - If set to true, then when serializing responses nestjs-zod will use encode instead of parse. See more information about codecs in the zod documentation

Examples

Creating a zod DTO

import { createZodDto } from 'nestjs-zod'
import { z } from 'zod'

const CredentialsSchema = z.object({
  username: z.string(),
  password: z.string(),
})

// class is required for using DTO as a type
class CredentialsDto extends createZodDto(CredentialsSchema) {}

Using a zod DTO

@Controller('auth')
class AuthController {
  async signIn(@Body() credentials: CredentialsDto) {}
}

ZodValidationPipe (Get nestjs to validate using zod)

ZodValidationPipe is needed to ensure zod DTOs actually validate incoming request data when using @Body(), @Params(), or @Query() parameter decorators

When the data is invalid it throws a ZodValidationException.

Example

Globally (recommended)

import { ZodValidationPipe } from 'nestjs-zod'
import { APP_PIPE } from '@nestjs/core'

@Module({
  providers: [
    {
      provide: APP_PIPE,
      useClass: ZodValidationPipe,
    },
  ],
})
export class AppModule {}

Locally

import { ZodValidationPipe } from 'nestjs-zod'

// controller-level
@UsePipes(ZodValidationPipe)
class AuthController {}

class AuthController {
  // route-level
  @UsePipes(ZodValidationPipe)
  async signIn() {}
}

createZodValidationPipe (Creating custom validation pipe)

export function createZodValidationPipe({ createValidationException, strictSchemaDeclaration }: ZodValidationPipeOptions = {}): ZodValidationPipeClass

Creates a custom zod validation pipe

Example

import { createZodValidationPipe } from 'nestjs-zod'

const MyZodValidationPipe = createZodValidationPipe({
  // provide custom validation exception factory
  createValidationException: (error: ZodError) =>
    new BadRequestException('Ooops'),
})

Parameters

• params.createValidationException - A callback that will be called with the zod error when a parsing error occurs. Should return a new instance of Error
• params.strictSchemaDeclaration - If true, throws a ZodSchemaDeclarationException when the pipe encounters a parameter that is not typed with a nestjs-zod DTO. It's recommended to set this to true to ensure all request data is properly validated

ZodValidationException

If the zod request parsing fails, then nestjs-zod will throw a ZodValidationException, which will result in the following HTTP response:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "code": "too_small",
      "minimum": 8,
      "type": "string",
      "inclusive": true,
      "message": "String must contain at least 8 character(s)",
      "path": ["password"]
    }
  ]
}

You can customize the exception and HTTP response by either 1) creating a custom validation pipe using createZodValidationPipe or 2) handling ZodValidationException inside an exception filter

Here is an example exception filter:

@Catch(ZodValidationException)
export class ZodValidationExceptionFilter implements ExceptionFilter {
  catch(exception: ZodValidationException) {
    exception.getZodError() // -> ZodError
  }
}

ZodSchemaDeclarationException

If strictSchemaDeclaration is set to true in createZodValidationPipe and a request parameter is not typed with a nestjs-zod DTO (e.g. using a primitive type like string or a class-validator DTO), then nestjs-zod will throw a ZodSchemaDeclarationException, which will result in the following HTTP response:

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

This is useful for catching cases during development where request data might not be properly validated. You can handle this exception in an exception filter if you want to customize the response:

@Catch(ZodSchemaDeclarationException)
export class ZodSchemaDeclarationExceptionFilter implements ExceptionFilter {
  catch(exception: ZodSchemaDeclarationException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    response.status(500).json({
      statusCode: 500,
      message: 'Missing nestjs-zod schema declaration',
    });
  }
}

Response Validation

ZodSerializerDto (Set zod DTO to serialize responses with)

function ZodSerializerDto(dto: ZodDto | UnknownSchema | [ZodDto] | [UnknownSchema])

Parses / serializes the return value of a controller method using the provided zod schema. This is especially useful to prevent accidental data leaks.

[!NOTE] Instead of ZodSerializerDto, consider using ZodResponse, which has some improvements over ZodSerializerDto

[!NOTE] For this feature to work, please ensure ZodSerializerInterceptor is setup correctly

Parameters

• options.dto - A ZodDto (or zod schema) to serialize the response with. If passed with array syntax ([MyDto]) then it will parse as an array. Note that the array syntax does not work with zod/mini, because it requires the schema have an .array() method

Example

const UserSchema = z.object({ username: string() })

class UserDto extends createZodDto(UserSchema) {}

@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @ZodSerializerDto(UserDto)
  getUser(id: number) {
    return this.userService.findOne(id)
  }
}

In the above example, if the userService.findOne method returns password, the password