/nestjs

name: nestjs
description: Use when building NestJS services. Covers module structure, providers and scopes, validation pipes, guards and interceptors, TypeORM/Prisma integration, and testing. Trigger on "nest can't resolve dependencies", "add a guard for auth", "validation pipe not working", "test my nest module". Do not use for API contract decisions like pagination or versioning — see the api-design skill.
metadata:
  category: backend
  version: 1.0.0
  tags: [nestjs, typescript, node, di, validation]

NestJS

Purpose

Build NestJS applications where the module graph reflects the domain, validation happens at the edge, and cross-cutting concerns live in guards and interceptors rather than being copied into every controller.

When to Use

• Building or reviewing a NestJS service.
• Structuring modules, providers, and their scopes.
• Implementing authentication, authorization, and request validation.
• Writing unit and end-to-end tests for a Nest application.

Capabilities

• Module and provider design, including dynamic modules.
• Validation with `class-validator` and the global `ValidationPipe`.
• Guards (authorization), interceptors (cross-cutting), filters (error mapping).
• Data access with Prisma or TypeORM, correctly scoped.
• Testing with the Nest testing module and Supertest.

Inputs

• The domain boundaries the modules should follow.
• The authentication scheme and the authorization model.
• The persistence layer.

Outputs

• Modules that encapsulate a domain and export only their public services.
• A global validation pipe with whitelisting enabled.
• Controllers that are thin, and services that contain the logic.

Workflow

1. **Model the modules on the domain** — One module per bounded capability, exporting the services other modules may use. A module that exports everything is not a boundary. 2. **Enable strict validation globally** — `whitelist: true` and `forbidNonWhitelisted: true`. Without these, a client can send extra fields and your DTO will happily carry them into the service. 3. **Push cross-cutting concerns out of controllers** — Auth in a guard, logging and timing in an interceptor, error mapping in an exception filter. 4. **Keep providers stateless and singleton** — Request-scoped providers cascade: anything that injects one becomes request-scoped too, and performance degrades quietly. 5. **Test at two levels** — Unit tests for services with mocked dependencies, and end-to-end tests through the real HTTP stack with a real (containerized) database.

Best Practices

• `ValidationPipe` without `whitelist: true` is decoration, not validation. Extra properties pass straight through.
• `transform: true` on the pipe converts payloads into DTO class instances — otherwise your `@Type` decorators and defaults do nothing.
• Circular module dependencies are a design smell. `forwardRef` is an escape hatch that hides a boundary you drew wrong.
• Do not inject the repository into the controller. The controller's job is HTTP; the service's job is the domain.
• Global exception filters map domain errors to HTTP status codes in one place. Throwing `HttpException` from a service couples the domain to the transport.
• Use `ConfigModule` with a validation schema so a missing environment variable fails at boot.

Examples

**Validation, guard, and thin controller:**

// main.ts
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,             // strip unknown properties
    forbidNonWhitelisted: true,  // and reject the request if any are present
    transform: true,             // instantiate the DTO class
  }),
);

export class CreateOrderDto {
  @IsUUID() customerId!: string;

  @IsArray()
  @ArrayMinSize(1)
  @ValidateNested({ each: true })
  @Type(() => OrderLineDto)
  lines!: OrderLineDto[];
}

@Controller("orders")
@UseGuards(JwtAuthGuard, TenantGuard)
export class OrdersController {
  constructor(private readonly orders: OrdersService) {}

  @Post()
  @HttpCode(HttpStatus.CREATED)
  create(@Body() dto: CreateOrderDto, @CurrentUser() user: User): Promise<OrderView> {
    return this.orders.place(user.tenantId, dto);
  }
}

**Domain errors mapped centrally:**

@Catch(DomainError)
export class DomainExceptionFilter implements ExceptionFilter {
  catch(error: DomainError, host: ArgumentsHost) {
    const status = {
      NOT_FOUND: 404,
      CONFLICT: 409,
      INVALID: 422,
    }[error.kind] ?? 400;

    host.switchToHttp().getResponse().status(status).json({
      type: `https://api.example.com/errors/${error.kind.toLowerCase()}`,
      title: error.message,
      status,
    });
  }
}

Notes

• Request-scoped providers instantiate a new instance per request and force the entire injection chain above them to do the same. Measure before using one.
• Nest's `TestingModule` lets you override any provider, which is almost always preferable to mocking a module's internals.
• Interceptors run around the handler and can transform the response. That makes them the right place for a response envelope — and the wrong place for business logic.