nest-best-practices

Skill based on NestJS documentation, updated 2026-03-28. Covers NestJS v11 with Express v5.

How to Use This Skill

NestJS v11 Breaking Changes

Node.js v20+ Required

Express v5 Route Matching

@Get('users/*')

@Get('users/*splat')

forRoutes('*')

forRoutes('{*splat}')

?

{}

CacheModule Migration to Keyv

CacheModule

cache-manager

// OLD (pre-v11) — no longer works
CacheModule.register({ store: redisStore, host: 'localhost', port: 6379 });

// NEW (v11+) — uses @keyv/redis
import { KeyvRedis } from '@keyv/redis';
CacheModule.registerAsync({
  useFactory: async () => ({
    stores: [new KeyvRedis('redis://localhost:6379')],
  }),
});

Production Best Practices

Bootstrap & Application Setup

ValidationPipe

main.ts

app.useGlobalPipes(new ValidationPipe({
  whitelist: true,           // strips unknown properties
  forbidNonWhitelisted: true, // rejects requests with unknown properties (400)
  transform: true,            // enables automatic type coercion for params
}));

Entity & Schema Discipline

• Use explicit column lengths:

  @Column({ length: 255 })

  , not bare

  @Column()

• Name tables explicitly:

  @Entity('books')

  to avoid surprises with naming conventions
• Use

  @CreateDateColumn()

  and

  @UpdateDateColumn()

  for automatic timestamps
• Use specialized validators like

  @IsISBN()

  ,

  @IsEmail()

  ,

  @IsUUID()

  — not just

  @IsString()

• Align nullability between entity and DTO: if

  @Column({ nullable: true })

  , the DTO field should be

  @IsOptional()

DTO Patterns

• Import

  PartialType

  from

  @nestjs/swagger

  (not

  @nestjs/mapped-types

  ) when using Swagger — this preserves API documentation metadata on partial fields
• Zod validation is now an officially supported alternative to

  class-validator

  — use

  ZodValidationPipe

  with

  z.infer<typeof schema>

  for schema-first validation with type inference

Guards & Auth

1. Native JWT (recommended for simpler cases): Use

   @nestjs/jwt

   directly with a custom

   CanActivate

   guard that calls

   JwtService.verifyAsync()

   . No Passport dependency needed.
2. Passport-based (for complex strategies like OAuth2, SAML): Use

   @nestjs/passport

   with

   PassportStrategy

   . Now documented under "recipes" rather than primary auth docs.

• Guard ordering matters:

  @UseGuards(JwtAuthGuard, RolesGuard)

  — JWT guard must run first to populate

  request.user

  before RolesGuard reads it
• Use

  Reflector.getAllAndOverride()

  (not just

  .get()

  ) so roles can be set at both handler and class level with handler taking precedence
• RolesGuard must throw

  ForbiddenException

  with a descriptive message when the user lacks the required role — do NOT just return

  false

  from

  canActivate()

  . The generic 403 provides no diagnostic value. Include context:

  throw new ForbiddenException(\

  Requires roles: ${requiredRoles.join(', ')}`)`
• Never hardcode JWT secrets — use

  JwtModule.registerAsync()

  with

  ConfigService

• Define a

  Role

  enum rather than raw strings for type safety
• In

  JwtStrategy.validate()

  (or native guard), validate the presence of required payload fields (

  sub

  ,

  username

  ,

  roles

  ) before returning the user object. Define a

  JwtPayload

  interface for type safety.

Error Messages

ForbiddenException

UnauthorizedException

NotFoundException

Microservices & Queues

• For hybrid apps (HTTP + microservice), use

  NestFactory.create()

  +

  app.connectMicroservice()

  pattern
• Always call

  app.enableShutdownHooks()

  when using Terminus health checks for graceful shutdown
• Use

  @nestjs/bullmq

  (not

  @nestjs/bull

  ) — it wraps the newer

  bullmq

  library. Config uses

  connection

  key (not

  redis

  ):
  typescript

  BullModule.forRoot({ connection: { host: 'localhost', port: 6379 } })

• Use

  BullModule.forRootAsync()

  with

  ConfigService

  injection for production config
• BullMQ consumers extend

  WorkerHost

  and implement

  process()

  — do NOT use the

  @Process()

  decorator (that's the older

  @nestjs/bull

  API)
• Register

  @OnWorkerEvent('completed')

  and

  @OnWorkerEvent('failed')

  lifecycle hooks for observability
• Set

  removeOnComplete: true

  and configure retry with

  backoff: { type: 'exponential' }

  on jobs
• Capture and log

  job.id

  from

  queue.add()

  return value for traceability
• Use

  job.updateProgress()

  for long-running jobs to enable monitoring dashboards
• Define and export TypeScript interfaces for all event payloads (e.g.,

  OrderCreatedEvent

  ,

  UserRegisteredEvent

  ) for type safety across service boundaries

Health Checks

• Don't just check one thing — include multiple indicators: service connectivity (Redis/DB), memory (heap + RSS), and disk usage
• Use

  MicroserviceHealthIndicator

  for transport checks,

  MemoryHealthIndicator

  for heap/RSS,

  DiskHealthIndicator

  for storage
• Configure graceful shutdown timeout:

  TerminusModule.forRoot({ gracefulShutdownTimeoutMs: 1000 })

OpenAPI / Swagger

@nestjs/swagger

@ApiProperty()

nest-cli.json

{
  "compilerOptions": {
    "plugins": [{
      "name": "@nestjs/swagger",
      "options": { "classValidatorShim": true, "introspectComments": true }
    }]
  }
}

@ApiProperty()

Testing

• @suites/unit

  is now a recommended testing library for NestJS:

  • TestBed.solitary(Service).compile()

    — all dependencies auto-mocked

  • TestBed.sociable(Service).expose(RealDep).compile()

    — selected real deps

  • Mocked<T>

    type for full IntelliSense on mock methods
  • Supports Jest, Vitest, and Sinon
• For e2e testing, use

  @nestjs/testing

  with

  Test.createTestingModule()

  and

  supertest

Custom Decorators

• For NestJS 10+, prefer

  Reflector.createDecorator<Role[]>()

  over

  SetMetadata

  for custom decorators — it provides better type inference and eliminates the need for a separate metadata key constant
• The

  SetMetadata

  pattern still works and is fine for simple cases

CLI

Core References

Fundamentals

Techniques

Security

OpenAPI

WebSockets

Microservices

GraphQL

Recipes

FAQ

Best Practices