| Standard (recommended) |
With this built-in method, when a route handler returns a JavaScript object or array, it is automatically
serialized to JSON. When it returns a JavaScript primitive type (e.g., string, number, boolean), Nest sends the value without attempting to serialize it. Response handling is therefore straightforward: return the value, and Nest takes care of the rest.
The response's status code is 200 by default, except for POST requests, which use 201. You can change this behavior by adding the @HttpCode(...)
decorator at the handler level (see Status code).
|
| Library-specific |
You can use the library-specific (e.g., Express) response object, injected with the @Res() decorator in the route handler signature (e.g., findAll(@Res() response)). This approach lets you use the native response handling methods exposed by that object. For example, with Express, you can construct responses with code like response.status(200).send().
|
@Request(), @Req() |
req |
@Response(), @Res()* |
res |
@Next() |
next |
@Session() |
req.session |
@Param(key?: string) |
req.params / req.params[key] |
@Body(key?: string) |
req.body / req.body[key] |
@Query(key?: string) |
req.query / req.query[key] |
@Headers(name?: string) |
req.headers / req.headers[name] |
@Cookies(name?: string) |
request cookies / the cookie named name (see Cookies) |
@SignedCookies(name?: string) |
verified signed cookies / the signed cookie named name |
@Ip() |
req.ip |
@HostParam() |
req.hosts |
duplicate |
Two routes share an identical method, path, host, and version. |
shadow |
Two route patterns can match the same request (e.g., /users/me and /users/:id). |
src
cats
dto
create-cat.dto.ts
interfaces
cat.interface.ts
cats.controller.ts
cats.service.ts
app.module.ts
main.ts
src
cats
dto
create-cat.dto.ts
interfaces
cat.interface.ts
cats.controller.ts
cats.module.ts
cats.service.ts
app.module.ts
main.ts
Middleware functions can perform the following tasks:You implement custom Nest middleware either as a function or as a class with the `@Injectable()` decorator. A class should implement the `NestMiddleware` interface, while a function has no special requirements. Let's start by implementing a simple middleware class. > warning **Warning** Express and Fastify handle middleware differently and provide different method signatures. See the [Performance (Fastify)](/http/performance#middleware) chapter for details. ```typescript import { Injectable, NestMiddleware } from '@nestjs/common'; import { Request, Response, NextFunction } from 'express'; @Injectable() export class LoggerMiddleware implements NestMiddleware { use(req: Request, res: Response, next: NextFunction) { console.log('Request...'); next(); } } ``` #### Dependency injection Nest middleware fully supports dependency injection. Like providers and controllers, middleware classes can **inject dependencies** that are available within the same module. As usual, dependencies are injected through the `constructor`. #### Applying middleware Middleware is not registered in the `@Module()` decorator. Instead, you set it up in the `configure()` method of the module class. Modules that include middleware must implement the `NestModule` interface. Let's set up the `LoggerMiddleware` at the `AppModule` level. ```typescript import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common'; import { LoggerMiddleware } from './common/middleware/logger.middleware.js'; import { CatsModule } from './cats/cats.module.js'; @Module({ imports: [CatsModule], }) export class AppModule implements NestModule { configure(consumer: MiddlewareConsumer) { consumer .apply(LoggerMiddleware) .forRoutes('cats'); } } ``` In the example above, the `LoggerMiddleware` is applied to the `/cats` route handlers defined in the `CatsController`. To restrict middleware to a particular request method, pass an object containing the route `path` and the request `method` to the `forRoutes()` method. The example below imports the `RequestMethod` enum to reference the desired request method. ```typescript import { Module, NestModule, RequestMethod, MiddlewareConsumer } from '@nestjs/common'; import { LoggerMiddleware } from './common/middleware/logger.middleware.js'; import { CatsModule } from './cats/cats.module.js'; @Module({ imports: [CatsModule], }) export class AppModule implements NestModule { configure(consumer: MiddlewareConsumer) { consumer .apply(LoggerMiddleware) .forRoutes({ path: 'cats', method: RequestMethod.GET }); } } ``` > info **Hint** The `configure()` method can be asynchronous. Declare it with `async` to `await` the completion of an asynchronous operation inside the method body. > warning **Warning** With the Express adapter, Nest registers the `json` and `urlencoded` body parsers (`express.json()` and `express.urlencoded()`) by default. To customize these parsers through the `MiddlewareConsumer`, disable the defaults by setting the `bodyParser` option to `false` when creating the application with `NestFactory.create()`. #### Route wildcards Middleware also supports pattern-based routes. For example, the named wildcard (`*splat`) matches any combination of characters in a route. In the following example, the middleware runs for any route that starts with `abcd/`, regardless of how many characters follow. ```typescript forRoutes({ path: 'abcd/*splat', method: RequestMethod.ALL, }); ``` > info **Hint** `splat` is only the name of the wildcard parameter and has no special meaning. You can use any name, e.g., `*wildcard`. The `'abcd/*splat'` route path matches `abcd/1`, `abcd/123`, `abcd/abc`, and so on. String-based paths interpret the hyphen (`-`) and the dot (`.`) literally. However, `abcd/` with no additional characters does not match. To match it as well, wrap the wildcard in braces to make it optional: ```typescript forRoutes({ path: 'abcd/{*splat}', method: RequestMethod.ALL, }); ``` #### Middleware consumer The `MiddlewareConsumer` is a helper class that provides several built-in methods to manage middleware. All of them can be **chained** in the [fluent style](https://en.wikipedia.org/wiki/Fluent_interface). The `forRoutes()` method accepts a single string, multiple strings, a `RouteInfo` object, a controller class, or multiple controller classes. In most cases, you'll pass a comma-separated list of **controllers**. Below is an example with a single controller: ```typescript import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common'; import { LoggerMiddleware } from './common/middleware/logger.middleware.js'; import { CatsModule } from './cats/cats.module.js'; import { CatsController } from './cats/cats.controller.js'; @Module({ imports: [CatsModule], }) export class AppModule implements NestModule { configure(consumer: MiddlewareConsumer) { consumer .apply(LoggerMiddleware) .forRoutes(CatsController); } } ``` > info **Hint** The `apply()` method accepts either a single middleware or multiple arguments to specify multiple middleware. #### Excluding routes To **exclude** certain routes from having middleware applied, use the `exclude()` method. It accepts a single string, multiple strings, or a `RouteInfo` object that identifies the routes to exclude: ```typescript consumer .apply(LoggerMiddleware) .exclude( { path: 'cats', method: RequestMethod.GET }, { path: 'cats', method: RequestMethod.POST }, 'cats/{*splat}', ) .forRoutes(CatsController); ``` With the example above, `LoggerMiddleware` is bound to all routes defined inside `CatsController` **except** those matching the three entries passed to the `exclude()` method. > info **Hint** The `exclude()` method supports wildcard parameters using the [path-to-regexp](https://github.com/pillarjs/path-to-regexp#parameters) package. #### Functional middleware The `LoggerMiddleware` class we've been using is minimal: it has no members, no additional methods, and no dependencies. Middleware like this can be defined as a plain function instead of a class. This type of middleware is called **functional middleware**. Let's convert the logger middleware from a class into a function to illustrate the difference: ```typescript import { Request, Response, NextFunction } from 'express'; export function logger(req: Request, res: Response, next: NextFunction) { console.log('Request...'); next(); } ``` Then use it within the `AppModule`: ```typescript consumer .apply(logger) .forRoutes(CatsController); ``` > info **Hint** Consider using **functional middleware** whenever your middleware doesn't need any dependencies. #### Multiple middleware To bind multiple middleware that execute sequentially, pass a comma-separated list to the `apply()` method: ```typescript consumer.apply(cors(), helmet(), logger).forRoutes(CatsController); ``` #### Global middleware To bind middleware to every registered route at once, use the `use()` method of the `INestApplication` instance: ```typescript const app = await NestFactory.create(AppModule); app.use(logger); await app.listen(process.env.PORT ?? 3000); ``` > info **Hint** Global middleware registered with `app.use()` cannot access the DI container, so use [functional middleware](middleware#functional-middleware) there. Alternatively, use a class middleware and bind it with `.forRoutes('*')` within the `AppModule` (or any other module). #### Error handling When middleware throws an exception, Nest's [exceptions layer](/exception-filters) catches it and sends an appropriate response, just as it does for exceptions thrown from a route handler. The recommended approach is to throw an `HttpException` (or a built-in subclass such as `UnauthorizedException`): ```typescript import { Injectable, NestMiddleware, UnauthorizedException, } from '@nestjs/common'; import { Request, Response, NextFunction } from 'express'; @Injectable() export class AuthMiddleware implements NestMiddleware { use(req: Request, res: Response, next: NextFunction) { if (!req.headers.authorization) { throw new UnauthorizedException(); } next(); } } ``` If the middleware is asynchronous, declare `use()` as `async` (or return a `Promise`) so that a rejected promise is forwarded to the exceptions layer: ```typescript @Injectable() export class AuthMiddleware implements NestMiddleware { constructor(private readonly authService: AuthService) {} async use(req: Request, res: Response, next: NextFunction) { const user = await this.authService.verify(req.headers.authorization); if (!user) { throw new UnauthorizedException(); } req['user'] = user; next(); } } ``` You can also pass the error to `next()`. This is useful when wrapping existing Express-style middleware that reports failures through the callback: ```typescript use(req: Request, res: Response, next: NextFunction) { if (!req.headers.authorization) { return next(new UnauthorizedException()); } next(); } ``` > warning **Warning** Because middleware runs before a route handler is selected, only **global** exception filters (registered with `app.useGlobalFilters()` or the `APP_FILTER` token) catch exceptions thrown from middleware. Method-scoped and controller-scoped filters are not invoked, and binding filters to a middleware class with `@UseFilters()` is not supported. > info **Hint** Middleware registered with `app.use()` is handled by the underlying HTTP platform (Express or Fastify), not by Nest's `MiddlewareModule`. Prefer throwing errors (or calling `next(err)`) from middleware bound with the `MiddlewareConsumer`, so that the exceptions layer can process them. --- # Exception filters Source: https://docs.nestjs.com/exception-filters Nest comes with a built-in **exceptions layer** that processes all unhandled exceptions across an application. When your application code does not handle an exception, this layer catches it and automatically sends an appropriate, user-friendly response.
- execute any code.
- make changes to the request and the response objects.
- end the request-response cycle.
- call the next middleware function in the stack.
- if the current middleware function does not end the request-response cycle, it must call
next()to pass control to the next middleware function. Otherwise, the request will be left hanging.
type
|
Indicates whether the argument is a body
(@Body()), query
(@Query()), param
(@Param()), or custom parameter (see
custom decorators). |
metatype
|
The metatype of the argument, for example,
String. The value is
undefined if you omit the type declaration in the route handler signature or use vanilla JavaScript.
|
data
|
The string passed to the decorator, for example,
@Body('string'). It's
undefined if you don't pass a string to the decorator, as in @Body(). |
schema
|
A Standard Schema compatible schema attached through parameter decorator options such as @Body({{ '{' }} schema {{ '}' }}) or @Param('id', {{ '{' }} schema {{ '}' }}). It's undefined if no schema is attached.
|
An ES2016 decorator is an expression which returns a function and can take a target, name and property descriptor as arguments.
You apply it by prefixing the decorator with an @ character and placing this at the very top of what
you are trying to decorate. Decorators can be defined for either a class, a method or a property.
#### Param decorators
Nest provides a set of **param decorators** that you can use in HTTP route handlers. The following table lists them along with the plain Express (or Fastify) objects they represent:
@Request(), @Req() |
req |
@Response(), @Res() |
res |
@Next() |
next |
@Session() |
req.session |
@Param(param?: string) |
req.params / req.params[param] |
@Body(param?: string) |
req.body / req.body[param] |
@Query(param?: string) |
req.query / req.query[param] |
@Headers(param?: string) |
req.headers / req.headers[param] |
@Ip() |
req.ip |
@HostParam(param?: string) |
req.hosts / req.hosts[param] |
DEFAULT |
A single instance of the provider is shared across the entire application. The instance lifetime is tied directly to the application lifecycle. Once the application has bootstrapped, all singleton providers have been instantiated. Singleton scope is the default. |
REQUEST |
A new instance of the provider is created exclusively for each incoming request. The instance is garbage-collected after the request has been processed. |
TRANSIENT |
Transient providers are not shared across consumers. Each consumer that injects a transient provider receives a new, dedicated instance. |
once complete (Promises resolved or rejected), all existing connections will be closed (`app.close()` called). | | `onApplicationShutdown()`\* | Called after connections close, as the last step of `app.close()`. | \* For these events, if you're not calling `app.close()` explicitly, you must opt in to make them work with system signals such as `SIGTERM`. See [Application shutdown](/fundamentals/lifecycle-events#application-shutdown) below. > warning **Warning** The lifecycle hooks listed above are not triggered for **request-scoped** classes. Request-scoped classes are not tied to the application lifecycle, and their lifespan is unpredictable. They are created exclusively for each request and garbage-collected after the response is sent. > info **Hint** Nest calls `onModuleInit()` and `onApplicationBootstrap()` module by module, ordered by each module's distance from the root module in the import graph: the most deeply imported modules (and global modules) go first, and the root module goes last. Each module's hooks are awaited before Nest moves on to the next module. The shutdown hooks run in the reverse order. #### Usage Each lifecycle hook is represented by an interface. Interfaces are technically optional because they do not exist after TypeScript compilation. Nonetheless, it's good practice to use them to benefit from strong typing and editor tooling. To register a lifecycle hook, implement the appropriate interface. For example, to register a method to be called during module initialization on a particular class (e.g., a controller, provider, or module), implement the `OnModuleInit` interface by supplying an `onModuleInit()` method: ```typescript import { Injectable, OnModuleInit } from '@nestjs/common'; @Injectable() export class UsersService implements OnModuleInit { onModuleInit() { console.log(`The module has been initialized.`); } } ``` #### Asynchronous initialization Both the `OnModuleInit` and `OnApplicationBootstrap` hooks let you defer the application initialization process. Return a `Promise`, or mark the method as `async` and `await` the completion of an asynchronous operation in the method body. ```typescript async onModuleInit(): Promise
createNestApplication()
|
Creates and returns a Nest application (INestApplication instance) based on the given module.
Note that you must manually initialize the application using the init() method.
|
createNestMicroservice()
|
Creates and returns a Nest microservice (INestMicroservice instance) based on the given module.
|
get()
|
Retrieves a static instance of a controller or provider (including guards, filters, etc.) available in the application context. Works like the same method of the module reference class. |
resolve()
|
Retrieves a dynamically created scoped instance (request or transient) of a controller or provider (including guards, filters, etc.) available in the application context. Works like the same method of the module reference class. |
select()
|
Navigates through the module's dependency graph; can be used to retrieve a specific instance from the selected module (used along with strict mode (strict: true) in the get() method).
|
| Option | Type | Description |
|---|---|---|
enableDebugMessages |
boolean |
If set to true, validator will print extra warning messages to the console when something is not right. |
skipUndefinedProperties |
boolean |
If set to true then validator will skip validation of all properties that are undefined in the validating object. |
skipNullProperties |
boolean |
If set to true then validator will skip validation of all properties that are null in the validating object. |
skipMissingProperties |
boolean |
If set to true then validator will skip validation of all properties that are null or undefined in the validating object. |
whitelist |
boolean |
If set to true, validator will strip validated (returned) object of any properties that do not use any validation decorators. |
forbidNonWhitelisted |
boolean |
If set to true, instead of stripping non-whitelisted properties validator will throw an exception. |
forbidUnknownValues |
boolean |
If set to true, attempts to validate unknown objects fail immediately. |
disableErrorMessages |
boolean |
If set to true, validation errors will not be returned to the client. |
errorHttpStatusCode |
number |
This setting allows you to specify which exception type will be used in case of an error. By default it throws BadRequestException. |
exceptionFactory |
Function |
Takes an array of the validation errors and returns an exception object to be thrown. |
groups |
string[] |
Groups to be used during validation of the object. |
always |
boolean |
Set default for always option of decorators. Default can be overridden in decorator options. |
strictGroups |
boolean |
If groups is not given or is empty, ignore decorators with at least one group. |
dismissDefaultMessages |
boolean |
If set to true, the validation will not use default messages. Error message always will be undefined if
its not explicitly set. |
validationError.target |
boolean |
Indicates if target should be exposed in ValidationError. |
validationError.value |
boolean |
Indicates if validated value should be exposed in ValidationError. |
stopAtFirstError |
boolean |
When set to true, validation of the given property will stop after encountering the first error. Defaults to false. |
errorFormat |
'list' | 'grouped' |
Specifies the format of validation error messages. 'list' (default) returns an array of error message strings. 'grouped' returns an object with property paths as keys and arrays of unmodified error messages as values, preserving custom validation messages without prepending parent path prefixes. |
| Option | Type | Description |
|---|---|---|
transform |
boolean |
If true, the handler receives the value produced by the schema. If false, it receives the original input after successful validation. Default: true. |
validateCustomDecorators |
boolean |
If true, parameters of custom decorators created with createParamDecorator() are validated as well. Default: false. |
validateOptions |
Record<string, unknown> |
Options forwarded to the schema's ~standard.validate() method, for libraries that support them. |
errorHttpStatusCode |
number |
The HTTP status code of the exception thrown when validation fails. Default: 400. |
exceptionFactory |
Function |
Receives the array of validation issues and returns the exception to throw. |
schema |
The default schema used when @SerializeOptions() doesn't provide one. |
validateOptions |
Options forwarded to the schema's ~standard.validate() method, for libraries that support them. A handler can override them with the validateOptions option of @SerializeOptions(). |
* * * * * *
| | | | | |
| | | | | day of week
| | | | months
| | | day of month
| | hours
| minutes
seconds (optional)
* * * * * * |
every second |
45 * * * * * |
every minute, on the 45th second |
0 10 * * * * |
every hour, at the start of the 10th minute |
0 */30 9-17 * * * |
every 30 minutes between 9am and 5pm |
0 30 11 * * 1-5 |
Monday to Friday at 11:30am |
name |
Lets you access and control a cron job after it's been declared. |
timeZone |
Specifies the time zone for the execution. This modifies the actual time relative to your time zone. If the time zone is invalid, an error is thrown. You can check all available time zones on the Moment Timezone website. |
utcOffset |
Specifies the offset of your time zone instead of using the timeZone option. Don't combine it with timeZone.
|
waitForCompletion |
If true, no additional instances of the cron job run until the current onTick callback completes. Any new scheduled executions that occur while the current cron job is running are skipped entirely.
|
disabled |
If true, the job is not executed at all (defaults to false).
|
| Local event listeners | Global event listeners | Handler method signature / When fired |
|---|---|---|
@OnQueueError() | @OnGlobalQueueError() | handler(error: Error) - An error occurred. error contains the triggering error. |
@OnQueueWaiting() | @OnGlobalQueueWaiting() | handler(jobId: number | string) - A job is waiting to be processed as soon as a worker is idle. jobId contains the ID of the job that has entered this state. |
@OnQueueActive() | @OnGlobalQueueActive() | handler(job: Job) - Job job has started. |
@OnQueueStalled() | @OnGlobalQueueStalled() | handler(job: Job) - Job job has been marked as stalled. This is useful for debugging job workers that crash or pause the event loop. |
@OnQueueProgress() | @OnGlobalQueueProgress() | handler(job: Job, progress: number) - Job job's progress was updated to value progress. |
@OnQueueCompleted() | @OnGlobalQueueCompleted() | handler(job: Job, result: any) - Job job successfully completed with a result result. |
@OnQueueFailed() | @OnGlobalQueueFailed() | handler(job: Job, err: Error) - Job job failed with reason err. |
@OnQueuePaused() | @OnGlobalQueuePaused() | handler() - The queue has been paused. |
@OnQueueResumed() | @OnGlobalQueueResumed() | handler() - The queue has been resumed. |
@OnQueueCleaned() | @OnGlobalQueueCleaned() | handler(jobs: Job[], type: string) - Old jobs have been cleaned from the queue. jobs is an array of cleaned jobs, and type is the type of jobs cleaned. |
@OnQueueDrained() | @OnGlobalQueueDrained() | handler() - Emitted whenever the queue has processed all the waiting jobs (even if some delayed jobs are not yet processed). |
@OnQueueRemoved() | @OnGlobalQueueRemoved() | handler(job: Job) - Job job was successfully removed. |
{{ '{' }}{{ '{' }}id{{ '}' }}{{ '}' }} prints {{ '{' }}id{{ '}' }}. For select, ordinals and exact matches, [use ICU message syntax](/application/i18n#use-icu-message-syntax).
> info **Hint** Only the `count` argument selects a plural form, so name it `count` in every plural message you translate with `t()`. Thanks to the registered catalog type, `t()` doesn't compile without it for plural messages. Validation messages get a `count` automatically, as [Localize validation messages](/application/i18n#localize-validation-messages) shows.
#### Localize exceptions
A missing order should produce a 404 in the customer's language. Translate the message when you throw:
```typescript
findOne(id: number): Order {
const order = this.orders.find((order) => order.id === id);
if (!order) {
throw new NotFoundException(this.i18nService.t('orders.notFound', { args: { id } }));
}
return order;
}
```
The exception carries the finished text, so there is nothing to configure: Nest's default exception filter, your own filters and GraphQL error formatting all receive the translated message. `GET /orders/999` with `x-lang: pl` returns:
```json
{
"message": "Nie znaleziono zamówienia #999.",
"error": "Not Found",
"statusCode": 404
}
```
Code that has no `I18nService` at hand can use the `t()` function instead. It translates for the current request in the same way. Built-in pipes such as `ParseIntPipe` produce English messages, so give the pipe that parses order IDs an exception factory:
```typescript
const orderIdPipe = new ParseIntPipe({
exceptionFactory: () => new BadRequestException(t('orders.invalidId')),
});
@Controller('orders')
export class OrdersController {
constructor(private readonly ordersService: OrdersService) {}
// ...
@Get(':id')
findOne(@Param('id', orderIdPipe) id: number) {
return this.ordersService.getSummary(id);
}
}
```
The pipe is created once, outside dependency injection, and still answers each request in its own language. You'll write `getSummary()` in [Format prices and dates](/application/i18n#format-prices-and-dates).
If your API shapes errors with its own [exception filter](/exception-filters#binding-filters), for example as RFC 9457 problem details, the filter reads the translated message like any other:
```typescript
import {
Catch,
NotFoundException,
type ArgumentsHost,
type ExceptionFilter,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';
@Catch(NotFoundException)
export class ProblemDetailsFilter implements ExceptionFilter {
constructor(private readonly httpAdapterHost: HttpAdapterHost) {}
catch(exception: NotFoundException, host: ArgumentsHost) {
const { httpAdapter } = this.httpAdapterHost;
const response = host.switchToHttp().getResponse();
httpAdapter.setHeader(response, 'Content-Type', 'application/problem+json');
httpAdapter.reply(
response,
{ type: 'about:blank', title: 'Not Found', status: 404, detail: exception.message },
404,
);
}
}
```
With the filter registered, the same request returns:
```json
{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "Nie znaleziono zamówienia #999."
}
```
#### Localize validation messages
This step assumes your application validates request bodies with `class-validator`; if it validates with Zod or another Standard Schema library, read on to [With Zod](#with-zod). `I18nValidationPipe` is a drop-in replacement for Nest's [`ValidationPipe`](/application/validation#using-the-built-in-validationpipe): it accepts the same options and only translates the messages. Bind it where `ValidationPipe` was, here as an `APP_PIPE` provider of `AppModule`:
```typescript
providers: [
{
provide: APP_PIPE,
useValue: new I18nValidationPipe({ whitelist: true, transform: true }),
},
],
```
Start with the DTO for new orders. It uses `class-validator` decorators without any messages:
```typescript
import { i18nValidationMessage } from '@nestjs/i18n';
import { Type } from 'class-transformer';
import { ArrayNotEmpty, IsInt, IsString, Max, Min, ValidateNested } from 'class-validator';
export class OrderItemDto {
@IsString()
productId: string;
@IsInt()
@Min(1)
@Max(10, { message: i18nValidationMessage('orders.tooManyItems') })
quantity: number;
}
export class CreateOrderDto {
@ArrayNotEmpty()
@ValidateNested({ each: true })
@Type(() => OrderItemDto)
items: OrderItemDto[];
}
```
A constraint without a `message` is looked up in the `validation` namespace by constraint name: `@IsInt()` reads `validation.isInt`, and `@Min()` reads `validation.min`. `i18nValidationMessage()` points a single constraint at a key of your choice, here a store-specific message for the item limit. Messages you write as plain strings are left alone. A message can use these placeholders:
- `property`: the field name, such as `quantity`.
- `path`: the dotted path from the DTO, such as `items.1.quantity`. For a top-level field, it's the same as `property`.
- `value`: the rejected value, when it's a string, number or boolean.
- `constraint1`, `constraint2` and so on: the decorator's arguments. A list, such as the values `@IsIn()` accepts, reads `US, PL, DE`.
- `count`: the first numeric argument, so a plural message agrees with it. `@Max(10)` selects the form for 10.
The item limit is a plural message (see the Polish catalog in [Translate order confirmations](/application/i18n#translate-order-confirmations)), so `@Max(10)` reads "10 sztuk" in Polish. Here is the Polish `validation` catalog for the constraints this tutorial uses. `minLength` is a plural message too, so `@MinLength(2)` reads "2 znaki" and `@MinLength(5)` "5 znaków":
```json
{
"isInt": "{path} musi być liczbą całkowitą",
"isString": "{path} musi być tekstem",
"min": "{path} musi wynosić co najmniej {constraint1}",
"arrayNotEmpty": "{path} musi zawierać co najmniej jeden element",
"minLength": {
"one": "{path} musi mieć co najmniej {count} znak",
"few": "{path} musi mieć co najmniej {count} znaki",
"many": "{path} musi mieć co najmniej {count} znaków",
"other": "{path} musi mieć co najmniej {count} znaku"
},
"matches": "{path} ma nieprawidłowy format"
}
```
A constraint that has no translation keeps the `class-validator` message, so you can translate the constraints you use one at a time.
For nested objects, Nest's `ValidationPipe` puts the parent path in front of each message. `I18nValidationPipe` leaves translated messages as they are, so each message decides for itself: `path` gives `items.1.quantity`, and `property` gives just `quantity`. Messages without a translation keep the prefix.
Customers set a shipping address on an order. Its DTO relies on the `minLength` and `matches` entries of the catalog, and names a store-specific message for the country:
```typescript
import { i18nValidationMessage } from '@nestjs/i18n';
import { IsIn, Matches, MinLength } from 'class-validator';
export class ShippingAddressDto {
@MinLength(2)
recipient: string;
@MinLength(2)
city: string;
@Matches(/^[0-9-]{5,6}$/)
postalCode: string;
@IsIn(['US', 'PL', 'DE'], { message: i18nValidationMessage('orders.unsupportedCountry') })
country: 'US' | 'PL' | 'DE';
}
```
```typescript
@Put(':id/shipping-address')
updateShippingAddress(
@Param('id', orderIdPipe) id: number,
@Body() address: ShippingAddressDto,
) {
return this.ordersService.updateShippingAddress(id, address);
}
```
A German customer who sends a one-letter recipient, a four-digit postal code and `AT` as the country gets three translated messages back. The [Try it](#try-it) section shows the response.
##### With Zod
If your application validates with Zod, Valibot, ArkType or another [Standard Schema](https://standardschema.dev/) library, bind `I18nStandardSchemaValidationPipe` instead of `I18nValidationPipe`. It's the drop-in replacement for Nest's [`StandardSchemaValidationPipe`](/application/validation#schema-based-validation), and an application binds one of the two pipes, not both:
```typescript
providers: [{ provide: APP_PIPE, useValue: new I18nStandardSchemaValidationPipe() }],
```
Here are the same inputs as Zod schemas. Library messages are plain strings, so `i18nIssueMessage()` encodes a translation key in the message itself, which works with any Standard Schema library:
```typescript
import { i18nIssueMessage } from '@nestjs/i18n';
import { z } from 'zod';
export const orderItemSchema = z.object({
productId: z.string(),
quantity: z.number().int().min(1).max(10, i18nIssueMessage('orders.tooManyItems')),
});
export const createOrderSchema = z.object({
items: z.array(orderItemSchema).nonempty(),
});
export type CreateOrderDto = z.infer