--- name: nestjs description: | NestJS enterprise Node.js framework. Covers modules, controllers, services, guards, and dependency injection. Use when building scalable Node.js applications. USE WHEN: user mentions "NestJS", "nest", "@nestjs", "@Module", "@Controller", "@Injectable", asks about "dependency injection in Node.js", "enterprise Node.js framework", "TypeScript backend framework", "decorators in backend", "guards and pipes", "modular Node.js architecture" DO NOT USE FOR: Express (minimalist framework) - use `express` instead, Fastify (performance-focused) - use `fastify` instead, Hono (edge runtimes) - use `hono` instead, Deno frameworks - use `oak` or `fresh` instead allowed-tools: Read, Grep, Glob, Write, Edit --- # NestJS Core Knowledge > **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `nestjs` for comprehensive documentation. ## Module Structure ```ts // users.module.ts @Module({ imports: [TypeOrmModule.forFeature([User])], controllers: [UsersController], providers: [UsersService], exports: [UsersService], }) export class UsersModule {} ``` ## Controller ```ts @Controller('users') export class UsersController { constructor(private readonly usersService: UsersService) {} @Get() findAll(): Promise { return this.usersService.findAll(); } @Get(':id') findOne(@Param('id') id: string): Promise { return this.usersService.findOne(id); } @Post() @HttpCode(201) create(@Body() createUserDto: CreateUserDto): Promise { return this.usersService.create(createUserDto); } @Put(':id') update(@Param('id') id: string, @Body() dto: UpdateUserDto) { return this.usersService.update(id, dto); } @Delete(':id') @HttpCode(204) remove(@Param('id') id: string) { return this.usersService.remove(id); } } ``` ## Service ```ts @Injectable() export class UsersService { constructor( @InjectRepository(User) private usersRepository: Repository, ) {} findAll(): Promise { return this.usersRepository.find(); } findOne(id: string): Promise { return this.usersRepository.findOneBy({ id }); } } ``` ## Key Decorators | Decorator | Purpose | |-----------|---------| | `@Module` | Define module | | `@Controller` | Define controller | | `@Injectable` | Mark as provider | | `@Get/@Post/@Put/@Delete` | HTTP methods | | `@Body/@Param/@Query` | Request data | | `@UseGuards` | Apply guards | | `@UsePipes` | Apply pipes | ## Production Readiness ### Security Configuration ```ts // main.ts - Security setup import { NestFactory } from '@nestjs/core'; import { ValidationPipe } from '@nestjs/common'; import helmet from 'helmet'; import * as compression from 'compression'; async function bootstrap() { const app = await NestFactory.create(AppModule); // Security headers app.use(helmet()); // CORS configuration app.enableCors({ origin: process.env.ALLOWED_ORIGINS?.split(',') || [], credentials: true, }); // Global validation pipe app.useGlobalPipes(new ValidationPipe({ whitelist: true, // Strip non-whitelisted properties forbidNonWhitelisted: true, // Throw on non-whitelisted transform: true, // Auto-transform payloads })); // Response compression app.use(compression()); // Rate limiting (with @nestjs/throttler) // Configured in AppModule await app.listen(process.env.PORT || 3000); } ``` ```ts // Rate limiting module import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler'; import { APP_GUARD } from '@nestjs/core'; @Module({ imports: [ ThrottlerModule.forRoot([{ ttl: 60000, // 1 minute limit: 100, // 100 requests per minute }]), ], providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard, }], }) export class AppModule {} ``` ### Health Checks ```ts // health.controller.ts import { Controller, Get } from '@nestjs/common'; import { HealthCheck, HealthCheckService, HttpHealthIndicator, TypeOrmHealthIndicator } from '@nestjs/terminus'; @Controller('health') export class HealthController { constructor( private health: HealthCheckService, private http: HttpHealthIndicator, private db: TypeOrmHealthIndicator, ) {} @Get() @HealthCheck() check() { return this.health.check([ () => this.db.pingCheck('database'), ]); } @Get('ready') @HealthCheck() readiness() { return this.health.check([ () => this.db.pingCheck('database'), () => this.http.pingCheck('external-api', 'https://api.example.com/health'), ]); } } ``` ### Logging ```ts // Structured logging with Pino import { LoggerModule } from 'nestjs-pino'; @Module({ imports: [ LoggerModule.forRoot({ pinoHttp: { level: process.env.LOG_LEVEL || 'info', transport: process.env.NODE_ENV !== 'production' ? { target: 'pino-pretty' } : undefined, redact: ['req.headers.authorization', 'req.body.password'], }, }), ], }) export class AppModule {} ``` ### Monitoring Metrics | Metric | Alert Threshold | |--------|-----------------| | Request latency p99 | > 500ms | | Error rate (5xx) | > 1% | | Memory usage | > 80% | | CPU usage | > 70% | | Active connections | > 1000 | | Request queue depth | > 100 | ### Exception Handling ```ts // Global exception filter @Catch() export class AllExceptionsFilter implements ExceptionFilter { constructor(private readonly logger: Logger) {} catch(exception: unknown, host: ArgumentsHost) { const ctx = host.switchToHttp(); const response = ctx.getResponse(); const request = ctx.getRequest(); const status = exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR; const message = exception instanceof HttpException ? exception.getResponse() : 'Internal server error'; this.logger.error({ statusCode: status, path: request.url, method: request.method, message, stack: exception instanceof Error ? exception.stack : undefined, }); response.status(status).json({ statusCode: status, message: status === 500 ? 'Internal server error' : message, timestamp: new Date().toISOString(), path: request.url, }); } } ``` ### Checklist - [ ] Helmet security headers enabled - [ ] CORS properly configured - [ ] Rate limiting implemented - [ ] Input validation with class-validator - [ ] Global exception filter - [ ] Health/readiness endpoints - [ ] Structured logging (no console.log) - [ ] Secrets via environment variables - [ ] HTTPS in production - [ ] Request timeout configured - [ ] Graceful shutdown handling ## When NOT to Use This Skill - **Minimalist APIs**: Use Express for lightweight, unopinionated APIs - **Maximum Performance**: Use Fastify for high-throughput, low-latency requirements - **Edge Runtimes**: Use Hono for Cloudflare Workers, Vercel Edge, or Deno Deploy - **Microservices Communication**: Defer to `kafka-expert` or `rabbitmq-expert` for message brokers - **Database Operations**: Use `prisma-expert` or `sql-expert` for ORM/database specifics - **WebSocket Implementation**: Use dedicated WebSocket skill (coming soon) ## Anti-Patterns | Anti-Pattern | Why It's Bad | Correct Approach | |--------------|--------------|------------------| | Using `console.log()` for logging | No structured logging, hard to query | Use `nestjs-pino` or Winston with structured logs | | Circular dependencies between modules | Causes initialization failures | Use `forwardRef()` or redesign module boundaries | | Business logic in controllers | Violates SRP, hard to test | Move logic to services, controllers orchestrate only | | Not using DTOs for validation | Security risk, inconsistent data | Use `class-validator` with DTOs for all inputs | | Hardcoding config values | Not portable, security risk | Use `@nestjs/config` with env variables | | Not implementing graceful shutdown | Data loss, incomplete requests | Handle `SIGTERM`, close connections properly | | Mixing ORM logic with business logic | Tight coupling, hard to test | Use repository pattern, inject repositories | | Not using guards for authorization | Security vulnerabilities | Implement guards for auth/authz checks | ## Quick Troubleshooting | Issue | Likely Cause | Solution | |-------|--------------|----------| | "Circular dependency detected" | Module A imports B, B imports A | Use `forwardRef()` or extract shared logic | | "Cannot find module" in tests | Path mapping not resolved | Configure `moduleNameMapper` in Jest config | | Guards not executing | Wrong order in app setup | Apply guards after pipes: `app.useGlobalGuards()` | | DTOs not validating | ValidationPipe not global | Add `app.useGlobalPipes(new ValidationPipe())` in main.ts | | High memory usage | Memory leaks in subscriptions | Use `takeUntil()` or unsubscribe in `onModuleDestroy()` | | Slow startup time | Too many providers/imports | Lazy load modules, optimize dependency tree | | 404 for all routes | Controllers not registered | Add controllers to module's `controllers` array | | Middleware not executing | Incorrect order or path | Check middleware order, use `forRoutes('*')` for global | ## Reference Documentation - [Module Structure](quick-ref/modules.md) - [Guards & Pipes](quick-ref/guards.md) - [Deep: Architecture](deep-docs/architecture/)