Nestjs Patterns

1---2name: nestjs-patterns3description: NestJS architecture patterns for modules, controllers, providers, DTO validation, guards, interceptors, config, and production-grade TypeScript backends.4origin: ECC5---6 7# NestJS Development Patterns8 9Production-grade NestJS patterns for modular TypeScript backends.10 11## When to Activate12 13- Building NestJS APIs or services14- Structuring modules, controllers, and providers15- Adding DTO validation, guards, interceptors, or exception filters16- Configuring environment-aware settings and database integrations17- Testing NestJS units or HTTP endpoints18 19## Project Structure20 21```text22src/23├── app.module.ts24├── main.ts25├── common/26│   ├── filters/27│   ├── guards/28│   ├── interceptors/29│   └── pipes/30├── config/31│   ├── configuration.ts32│   └── validation.ts33├── modules/34│   ├── auth/35│   │   ├── auth.controller.ts36│   │   ├── auth.module.ts37│   │   ├── auth.service.ts38│   │   ├── dto/39│   │   ├── guards/40│   │   └── strategies/41│   └── users/42│       ├── dto/43│       ├── entities/44│       ├── users.controller.ts45│       ├── users.module.ts46│       └── users.service.ts47└── prisma/ or database/48```49 50- Keep domain code inside feature modules.51- Put cross-cutting filters, decorators, guards, and interceptors in `common/`.52- Keep DTOs close to the module that owns them.53 54## Bootstrap and Global Validation55 56```ts57async function bootstrap() {58  const app = await NestFactory.create(AppModule, { bufferLogs: true });59 60  app.useGlobalPipes(61    new ValidationPipe({62      whitelist: true,63      forbidNonWhitelisted: true,64      transform: true,65      transformOptions: { enableImplicitConversion: true },66    }),67  );68 69  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));70  app.useGlobalFilters(new HttpExceptionFilter());71 72  await app.listen(process.env.PORT ?? 3000);73}74bootstrap();75```76 77- Always enable `whitelist` and `forbidNonWhitelisted` on public APIs.78- Prefer one global validation pipe instead of repeating validation config per route.79 80## Modules, Controllers, and Providers81 82```ts83@Module({84  controllers: [UsersController],85  providers: [UsersService],86  exports: [UsersService],87})88export class UsersModule {}89 90@Controller('users')91export class UsersController {92  constructor(private readonly usersService: UsersService) {}93 94  @Get(':id')95  getById(@Param('id', ParseUUIDPipe) id: string) {96    return this.usersService.getById(id);97  }98 99  @Post()100  create(@Body() dto: CreateUserDto) {101    return this.usersService.create(dto);102  }103}104 105@Injectable()106export class UsersService {107  constructor(private readonly usersRepo: UsersRepository) {}108 109  async create(dto: CreateUserDto) {110    return this.usersRepo.create(dto);111  }112}113```114 115- Controllers should stay thin: parse HTTP input, call a provider, return response DTOs.116- Put business logic in injectable services, not controllers.117- Export only the providers other modules genuinely need.118 119## DTOs and Validation120 121```ts122export class CreateUserDto {123  @IsEmail()124  email!: string;125 126  @IsString()127  @Length(2, 80)128  name!: string;129 130  @IsOptional()131  @IsEnum(UserRole)132  role?: UserRole;133}134```135 136- Validate every request DTO with `class-validator`.137- Use dedicated response DTOs or serializers instead of returning ORM entities directly.138- Avoid leaking internal fields such as password hashes, tokens, or audit columns.139 140## Auth, Guards, and Request Context141 142```ts143@UseGuards(JwtAuthGuard, RolesGuard)144@Roles('admin')145@Get('admin/report')146getAdminReport(@Req() req: AuthenticatedRequest) {147  return this.reportService.getForUser(req.user.id);148}149```150 151- Keep auth strategies and guards module-local unless they are truly shared.152- Encode coarse access rules in guards, then do resource-specific authorization in services.153- Prefer explicit request types for authenticated request objects.154 155## Exception Filters and Error Shape156 157```ts158@Catch()159export class HttpExceptionFilter implements ExceptionFilter {160  catch(exception: unknown, host: ArgumentsHost) {161    const response = host.switchToHttp().getResponse<Response>();162    const request = host.switchToHttp().getRequest<Request>();163 164    if (exception instanceof HttpException) {165      return response.status(exception.getStatus()).json({166        path: request.url,167        error: exception.getResponse(),168      });169    }170 171    return response.status(500).json({172      path: request.url,173      error: 'Internal server error',174    });175  }176}177```178 179- Keep one consistent error envelope across the API.180- Throw framework exceptions for expected client errors; log and wrap unexpected failures centrally.181 182## Config and Environment Validation183 184```ts185ConfigModule.forRoot({186  isGlobal: true,187  load: [configuration],188  validate: validateEnv,189});190```191 192- Validate env at boot, not lazily at first request.193- Keep config access behind typed helpers or config services.194- Split dev/staging/prod concerns in config factories instead of branching throughout feature code.195 196## Persistence and Transactions197 198- Keep repository / ORM code behind providers that speak domain language.199- For Prisma or TypeORM, isolate transactional workflows in services that own the unit of work.200- Do not let controllers coordinate multi-step writes directly.201 202## Testing203 204```ts205describe('UsersController', () => {206  let app: INestApplication;207 208  beforeAll(async () => {209    const moduleRef = await Test.createTestingModule({210      imports: [UsersModule],211    }).compile();212 213    app = moduleRef.createNestApplication();214    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));215    await app.init();216  });217});218```219 220- Unit test providers in isolation with mocked dependencies.221- Add request-level tests for guards, validation pipes, and exception filters.222- Reuse the same global pipes/filters in tests that you use in production.223 224## Production Defaults225 226- Enable structured logging and request correlation ids.227- Terminate on invalid env/config instead of booting partially.228- Prefer async provider initialization for DB/cache clients with explicit health checks.229- Keep background jobs and event consumers in their own modules, not inside HTTP controllers.230- Make rate limiting, auth, and audit logging explicit for public endpoints.