nestjs-best-practices

Original：🇺🇸 English
Translated

NestJS 11+ best practices for enterprise Node.js applications with TypeScript. Use when writing, reviewing, or refactoring NestJS controllers, services, modules, or APIs. Triggers on: NestJS modules, controllers, providers, dependency injection, @Injectable, @Controller, @Module, middleware, guards, interceptors, pipes, exception filters, ValidationPipe, class-validator, class-transformer, DTOs, JWT authentication, Passport strategies, @nestjs/passport, TypeORM entities, Prisma client, Drizzle ORM, repository pattern, circular dependencies, forwardRef, @nestjs/swagger, OpenAPI decorators, GraphQL resolvers, @nestjs/graphql, microservices, TCP transport, Redis transport, NATS, Kafka, NestJS 11 breaking changes, Express v5 migration, custom decorators, ConfigService, @nestjs/config, health checks, or NestJS testing patterns.

4installs
Sourceejirocodes/agent-skills
Added on

NPX Install

npx skill4agent add ejirocodes/agent-skills nestjs-best-practices

Tags

Translated version includes tags in frontmatter
nestjs-11nodejs-enterprisetypescript-backendnestjs-best-practicesbackend-architecture

SKILL.md Content

View Translation Comparison →

NestJS 11 Best Practices

Quick Reference

TopicWhen to UseReference
Core ArchitectureModules, Providers, DI, forwardRef, custom decoratorscore-architecture.md
Request LifecycleMiddleware, Guards, Interceptors, Pipes, Filtersrequest-lifecycle.md
Validation & PipesDTOs, class-validator, ValidationPipe, transformsvalidation-pipes.md
AuthenticationJWT, Passport, Guards, Local/OAuth strategies, RBACauthentication.md
DatabaseTypeORM, Prisma, Drizzle ORM, repository patternsdatabase-integration.md
TestingUnit tests, E2E tests, mocking providerstesting.md
OpenAPI & GraphQLSwagger decorators, resolvers, subscriptionsopenapi-graphql.md
MicroservicesTCP, Redis, NATS, Kafka patternsmicroservices.md

Essential Patterns

Module with Providers

typescript
@Module({
  imports: [DatabaseModule],
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService], // Export for other modules
})
export class UsersModule {}

Controller with Validation

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

  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }

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

DTO with Validation

typescript
import { IsEmail, IsString, MinLength, IsOptional } from 'class-validator';

export class CreateUserDto {
  @IsEmail()
  email: string;

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

  @IsOptional()
  @IsString()
  name?: string;
}

Exception Filter

typescript
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const status = exception.getStatus();

    response.status(status).json({
      statusCode: status,
      message: exception.message,
      timestamp: new Date().toISOString(),
    });
  }
}

Guard with JWT

typescript
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  canActivate(context: ExecutionContext) {
    return super.canActivate(context);
  }
}

NestJS 11 Breaking Changes

  • Express v5: Wildcards must be named (e.g., 
    *splat
    ), optional params use braces 
    /:file{.:ext}
  • Node.js 20+: Minimum required version
  • Fastify v5: Updated adapter for Fastify users
  • Dynamic Modules: Same module with identical config imported multiple times = separate instances

Common Mistakes

  1. Not using 
    forwardRef()
    for circular deps     - Causes "cannot resolve dependency" errors; wrap in 
    forwardRef(() => ModuleName)
  2. Throwing plain errors instead of HttpException - Loses status codes, breaks exception filters; use 
    throw new BadRequestException('message')
  3. Missing 
    @Injectable()
    decorator     - Provider won't be injectable; always decorate services
  4. Global ValidationPipe without 
    whitelist: true
     - Allows unexpected properties; set 
    whitelist: true, forbidNonWhitelisted: true
  5. Importing modules instead of exporting providers - Use 
    exports
    array to share providers across modules
  6. Async config without 
    ConfigModule.forRoot()
     - ConfigService undefined; import ConfigModule in AppModule
  7. Testing without 
    overrideProvider()
     - Uses real services in unit tests; mock dependencies with 
    overrideProvider(Service).useValue(mock)
  8. E2E tests sharing database state - No isolation between tests; use transactions or truncate tables in beforeEach