How does NestJS use decorators?

Question

Accepted Answer

NestJS is built around **TypeScript decorators** — special `@`-prefixed annotations that attach **metadata** to classes, methods, and parameters. NestJS reads this metadata (via reflection) to wire up routing, dependency injection, validation, and more declaratively. Decorators are everywhere in Nest.

## Class decorators — define the role of a class

```ts
@Controller("users")     // this class is a CONTROLLER, prefix /users
export class UsersController {}

@Injectable()            // this class is a PROVIDER (injectable)
export class UsersService {}

@Module({ ... })         // this class is a MODULE
export class UsersModule {}
```

Class decorators declare what a class *is* in the NestJS architecture (controller, provider, module) and configure it.

## Method decorators — map routes and apply behavior

```ts
@Get()                   // GET request handler
@Post()                  // POST handler
@Get(":id")              // GET /users/:id
@HttpCode(204)           // set the response status code
@UseGuards(AuthGuard)    // apply a guard to this route
@UseInterceptors(LoggingInterceptor)
findAll() {}
```

## Parameter decorators — extract request data

```ts
findOne(
  @Param("id") id: string,       // route parameter
  @Query("sort") sort: string,   // query string
  @Body() dto: CreateUserDto,    // request body
  @Headers("auth") auth: string, // header
) {}
```

Parameter decorators declaratively pull exactly the data you need out of the request — no manual `req` parsing.

## Property/validation decorators (on DTOs)

```ts
export class CreateUserDto {
  @IsEmail()                     // validation rules (class-validator)
  email: string;

@IsString()
  @MinLength(8)
  password: string;
}
```

## Why decorators? Declarative metadata

```text
Decorators attach METADATA that NestJS reads at runtime (via reflection) to:
  ✓ Register routes (@Get, @Controller)
  ✓ Wire dependency injection (@Injectable, @Inject)
  ✓ Apply guards/interceptors/pipes (@UseGuards, etc.)
  ✓ Validate input (@IsEmail, @IsString)
→ Behavior is declared WHERE it applies, concisely and readably.
```

## Custom decorators

```ts
// you can create your own — e.g. extract the current user from the request
export const CurrentUser = createParamDecorator((data, ctx) =>
  ctx.switchToHttp().getRequest().user
);
// usage: findProfile(@CurrentUser() user: User) {}
```

## Why it matters

Decorators are the defining syntactic feature of NestJS — the entire framework is organized around them, so understanding how they work is essential to reading and writing any NestJS code.

They provide a **declarative**, metadata-driven approach: instead of imperative configuration, you annotate classes, methods, and parameters to declare routing (`@Controller`, `@Get`), dependency injection (`@Injectable`), cross-cutting behavior (`@UseGuards`, `@UseInterceptors`), and validation (`@IsEmail`) right where they apply — concise and readable.

This metadata-via-reflection mechanism (the same idea behind Angular and Java/Spring annotations) is what enables NestJS's clean, structured style.

Recognizing the categories (class, method, parameter, property decorators), knowing the common ones, and being able to create custom decorators is fundamental NestJS fluency — decorators are how nearly every feature is expressed, making them one of the first and most important things to understand in the framework.