nestjs-patterns

NestJS Development Patterns

Production-grade NestJS patterns for modular TypeScript backends.

When to Activate

• Building NestJS APIs or services
• Structuring modules, controllers, and providers
• Adding DTO validation, guards, interceptors, or exception filters
• Configuring environment-aware settings and database integrations
• Testing NestJS units or HTTP endpoints

Project Structure

src/
├── app.module.ts
├── main.ts
├── common/
│   ├── filters/
│   ├── guards/
│   ├── interceptors/
│   └── pipes/
├── config/
│   ├── configuration.ts
│   └── validation.ts
├── modules/
│   ├── auth/
│   │   ├── auth.controller.ts
│   │   ├── auth.module.ts
│   │   ├── auth.service.ts
│   │   ├── dto/

• Keep domain code inside feature modules.
• Put cross-cutting filters, decorators, guards, and interceptors in common/.
• Keep DTOs close to the module that owns them.

Bootstrap and Global Validation

• Always enable whitelist and forbidNonWhitelisted on public APIs.
• Prefer one global validation pipe instead of repeating validation config per route.

Modules, Controllers, and Providers

• Controllers should stay thin: parse HTTP input, call a provider, return response DTOs.
• Put business logic in injectable services, not controllers.
• Export only the providers other modules genuinely need.

DTOs and Validation

• Validate every request DTO with class-validator.
• Use dedicated response DTOs or serializers instead of returning ORM entities directly.
• Avoid leaking internal fields such as password hashes, tokens, or audit columns.

Auth, Guards, and Request Context

• Keep auth strategies and guards module-local unless they are truly shared.
• Encode coarse access rules in guards, then do resource-specific authorization in services.
• Prefer explicit request types for authenticated request objects.

Exception Filters and Error Shape

• Keep one consistent error envelope across the API.
• Throw framework exceptions for expected client errors; log and wrap unexpected failures centrally.

Config and Environment Validation

• Validate env at boot, not lazily at first request.
• Keep config access behind typed helpers or config services.
• Split dev/staging/prod concerns in config factories instead of branching throughout feature code.

Persistence and Transactions

• Keep repository / ORM code behind providers that speak domain language.
• For Prisma or TypeORM, isolate transactional workflows in services that own the unit of work.
• Do not let controllers coordinate multi-step writes directly.

Testing

• Unit test providers in isolation with mocked dependencies.
• Add request-level tests for guards, validation pipes, and exception filters.
• Reuse the same global pipes/filters in tests that you use in production.

Production Defaults

• Enable structured logging and request correlation ids.
• Terminate on invalid env/config instead of booting partially.
• Prefer async provider initialization for DB/cache clients with explicit health checks.
• Keep background jobs and event consumers in their own modules, not inside HTTP controllers.
• Make rate limiting, auth, and audit logging explicit for public endpoints.