nestjs-zod

You can externalize and reuse schemas in your OpenAPI documentation by adding .meta({ id: "SchemaName" }) to a Zod schema. This adds the schema directly to components.schemas in the OpenAPI output.

Naming Logic

1. Input Schemas: Use the id provided in .meta({ id: 'MySchema' }).
2. Output Schemas: nestjs-zod automatically suffixes the id with _Output (e.g., MySchema_Output) to prevent collisions with input schemas.
3. Titles: If .meta({ title: 'CustomTitle' }) is used, that title is used instead of the ID.

const Author = z.object({ name: z.string() }).meta({ id: "Author" })

class BookDto extends createZodDto(z.object({ title: z.string(), author: Author })) { }
// Result: 'Author' will be a reusable component in OpenAPI

ZodValidationException

Thrown when request parsing fails. It returns a 400 status code with an errors array containing Zod error details. You can handle this using a NestJS ExceptionFilter and calling exception.getZodError() to access the raw ZodError.

ZodSchemaDeclarationException

Thrown when strictSchemaDeclaration is enabled and a parameter lacks a nestjs-zod DTO. This results in a 500 status code. You can handle this with an ExceptionFilter to provide a custom response.

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

With the new OpenAPI generation in version 5.x, you can distinguish between 'input' and 'output' schemas:

1. Input Schema: Represents the data shape required to pass validation. This is the default for DTOs created via createZodDto.
2. Output Schema: Represents the return value of parsing.

To use the output version in Swagger, use the .Output property on your DTO (e.g., @ApiResponse({ type: Car.Output })) or use the @ZodResponse decorator, which uses the output version automatically.

To install nestjs-zod manually, use npm. Note that zod version ^3.25.0 or ^4.0.0 is also required as a peer dependency.

npm install nestjs-zod

The function zodToOpenAPI is deprecated in version 5.x and has been renamed to zodV3ToOpenAPI.

Note: If you are using Zod v4, you should consider using the built-in z.toJSONSchema(schema) method instead of this library's utility, as zodToOpenAPI is slated for removal.

- const openApi = zodToOpenAPI(MySchema);
+ const openApi = zodV3ToOpenAPI(MySchema);

To integrate nestjs-zod into your NestJS application, you need to configure three main components:

1. Validation and Serialization: Register ZodValidationPipe and ZodSerializerInterceptor in your AppModule (or globally) to enable automatic request validation and response serialization using Zod schemas.
2. OpenAPI Integration: Use cleanupOpenApiDoc in your main.ts to ensure that the generated OpenAPI/Swagger documentation is cleaned up and correctly reflects your Zod-based schemas.
3. Error Handling: Implement a custom HttpExceptionFilter to catch Zod validation errors and format them into consistent, user-friendly HTTP error responses.

This package is a TypeScript starter repository using the NestJS framework with ESM support.

Project Setup

Install dependencies using pnpm:

pnpm install

Running the Application

Use the following commands to manage the application lifecycle:

• Development: Run the project normally.
• Watch Mode: Run the project with hot-reloading enabled.
• Production: Run the compiled production build.

Running Tests

Execute the test suite using these commands:

• Unit Tests: Run the unit test suite.
• E2E Tests: Run end-to-end tests.
• Test Coverage: Run tests and generate a coverage report.

# development
$ pnpm run start

# watch mode
$ pnpm run start:dev

# production mode
$ pnpm run start:prod

# unit tests
$ pnpm run test

# e2e tests
$ pnpm run test:e2e

# test coverage
$ pnpm run test:cov

You can automatically configure nestjs-zod in your NestJS project using the CLI. This runs a codemod that automatically adds the ZodValidationPipe, ZodSerializerInterceptor, HttpExceptionFilter, and the cleanupOpenApiDoc function to your project.

Run the following command, replacing /path/to/nestjs/project with the actual path to your project root:

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

To enable validation for request bodies, query parameters, and URL parameters, you must add ZodValidationPipe to your AppModule providers using the APP_PIPE token.

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

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

In version 5.x, patchNestJsSwagger() has been replaced by cleanupOpenApiDoc(). Instead of monkey-patching NestJS, you must now call cleanupOpenApiDoc() with your generated OpenAPI document before passing it to SwaggerModule.setup().

- patchNestJsSwagger()
- SwaggerModule.setup('api/zod-v3', app, openApiDoc);
+ SwaggerModule.setup('api/zod-v3', app, cleanupOpenApiDoc(openApiDoc));

This project is a NestJS framework TypeScript starter repository. Use pnpm to manage dependencies and run the application in various modes.

Installation

Install dependencies using:

pnpm install

Running the application

• Development mode: pnpm run start
• Watch mode (auto-reload on changes): pnpm run start:dev
• Production mode: pnpm run start:prod

$ pnpm install

# development
$ pnpm run start

# watch mode
$ pnpm run start:dev

# production mode
$ pnpm run start:prod