/api-framework-nestjs

name: api-framework-nestjs
description: NestJS backend framework - modules, controllers, services, DI, guards, pipes, interceptors, exception filters, middleware, DTOs with class-validator

NestJS Patterns

> **Quick Guide:** NestJS is an opinionated, modular Node.js framework built on TypeScript. Use modules to organize features, controllers for HTTP routing, services for business logic with dependency injection, DTOs with class-validator for validation, guards for auth, and exception filters for error handling. Key gotchas: always register services in module `providers`, always enable `ValidationPipe` globally with `whitelist: true`, never put business logic in controllers, never instantiate services with `new`. NestJS 11 is the current stable version (opt-in SWC compiler, Express v5, reversed termination hooks).

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use `@Injectable()` on every service and register it in the module `providers` array)**

**(You MUST enable `ValidationPipe` globally with `whitelist: true` and `forbidNonWhitelisted: true`)**

**(You MUST use DTOs with class-validator decorators for ALL request body validation — never validate manually in controllers)**

**(You MUST throw NestJS built-in HTTP exceptions (`NotFoundException`, `BadRequestException`, etc.) — never send raw status codes)**

**(You MUST use constructor injection for dependencies — never instantiate services manually with `new`)**

</critical_requirements>

---

**Auto-detection:** NestJS, @nestjs/common, @nestjs/core, @Module, @Controller, @Injectable, @Get, @Post, @Body, @Param, @Query, @UseGuards, @UseInterceptors, @UsePipes, @UseFilters, CanActivate, NestInterceptor, PipeTransform, ExceptionFilter, ValidationPipe, class-validator, class-transformer

**When to use:**

• Building structured backend APIs with TypeScript and dependency injection
• Applications requiring modular architecture with clear separation of concerns
• REST APIs with declarative validation, authentication, and role-based access
• Projects needing the guard/interceptor/pipe/filter request lifecycle

**When NOT to use:**

• Simple scripts or serverless functions that don't need a framework
• Projects where Express/Fastify alone is sufficient (no DI, no modules needed)
• Frontend code

**Detailed Resources:**

• [examples/core.md](examples/core.md) — Feature modules, CRUD, DTOs, dynamic modules, exception filters, custom providers
• [examples/database.md](examples/database.md) — NestJS DI patterns for database integration, transactions
• [examples/auth.md](examples/auth.md) — Passport.js integration, JWT strategy, auth guards, RBAC
• [examples/testing.md](examples/testing.md) — Unit testing with `Test.createTestingModule`, e2e with supertest
• [examples/advanced.md](examples/advanced.md) — Interceptors, custom pipes, custom decorators, config, CQRS, Swagger
• [reference.md](reference.md) — CLI commands, project structure, decorator tables, decision frameworks

---

<philosophy>

Philosophy

NestJS enforces a **modular, decorator-driven architecture** inspired by Angular. Every feature is organized into modules containing controllers (HTTP layer), services (business logic), and supporting infrastructure (guards, pipes, interceptors, filters).

**Core principles:**

1. **Modularity** — Group related controllers, services, and providers into feature modules. Modules are the primary organizational unit. 2. **Dependency injection** — Never instantiate services manually. Declare them as `@Injectable()` and let NestJS resolve the dependency graph via constructor injection. 3. **Decorator-driven** — Decorators (`@Controller`, `@Get`, `@Body`, `@UseGuards`) attach metadata that NestJS uses to build routing, validation, and middleware pipelines. 4. **Separation of concerns** — Controllers handle HTTP request/response. Services handle business logic. Guards handle authorization. Pipes handle validation/transformation. Filters handle exceptions. 5. **Convention over configuration** — Follow NestJS conventions (one module per feature, one controller per resource, DTOs for validation) to get batteries-included functionality.

</philosophy>

---

<patterns>

Key Patterns

Module System

Every NestJS app has a root `AppModule` that imports feature modules. Each feature module groups its controller, service, and providers. Export services that other modules need.

// Feature module — one per resource
@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService], // Available to other modules
})
export class UsersModule {}

**Why good:** Encapsulation per feature, explicit dependency graph via imports/exports, testable in isolation

See [examples/core.md](examples/core.md) for complete CRUD module, dynamic modules, and custom providers.

---

Controllers — Thin Routing Layer

Controllers should only extract request data and delegate to services. No business logic.

@Controller("users")
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get(":id")
  findOne(@Param("id", ParseIntPipe) id: number) {
    return this.usersService.findOne(id);
  }

  @Post()
  @HttpCode(HttpStatus.CREATED)
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
}

**Why good:** `ParseIntPipe` validates and converts param, `@HttpCode` for explicit status, thin delegation to service

**Anti-pattern:** Business logic, manual validation, or database access in controllers — always delegate to services.

---

DTOs with class-validator

Use DTOs with class-validator decorators for all request validation. Enable `ValidationPipe` globally.

const MIN_PASSWORD_LENGTH = 8;

export class CreateUserDto {
  @IsEmail()
  email: str