NestJS Expert Development Skill

A Claude Code skill for building enterprise-grade Node.js applications with NestJS — covering module architecture, dependency injection, decorators, guards, interceptors, pipes, and microservices patterns.

When to Use This Skill

Choose this skill when:

• Building a new backend API with NestJS
• Implementing authentication, authorization, and guards
• Designing module architecture with dependency injection
• Creating microservices or event-driven architectures
• Adding WebSocket, GraphQL, or gRPC endpoints
• Writing integration tests for NestJS applications

Consider alternatives when:

• You need a lightweight API (use Express or Fastify directly)
• You need a serverless-first framework (use Hono or AWS Lambda)
• You need a Python backend (use FastAPI or Django)

Quick Start

Copy
# Install NestJS CLI
npm install -g @nestjs/cli

# Create new project
nest new my-api
cd my-api

# Generate resources
nest generate module users
nest generate controller users
nest generate service users

Copy
// src/users/users.controller.ts
import { Controller, Get, Post, Body, Param, UseGuards } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';
import { AuthGuard } from '../auth/auth.guard';

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

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

  @UseGuards(AuthGuard)
  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(id);
  }
}

Core Concepts

NestJS Building Blocks

Block	Purpose	Decorator
Module	Organize application structure	@Module()
Controller	Handle HTTP requests	@Controller()
Service	Business logic and data access	@Injectable()
Guard	Authorization and access control	@UseGuards()
Interceptor	Transform responses, add logging	@UseInterceptors()
Pipe	Validate and transform input	@UsePipes()
Middleware	Request preprocessing	implements NestMiddleware
Filter	Exception handling	@Catch()

Module Architecture

Copy
// src/app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        type: 'postgres',
        url: config.get('DATABASE_URL'),
        autoLoadEntities: true,
        synchronize: false,
      }),
      inject: [ConfigService],
    }),
    AuthModule,
    UsersModule,
    OrdersModule,
  ],
})
export class AppModule {}

Guards and Authentication

Copy
// src/auth/auth.guard.ts
@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private jwtService: JwtService) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = this.extractToken(request);
    if (!token) throw new UnauthorizedException();

    try {
      request.user = await this.jwtService.verifyAsync(token);
      return true;
    } catch {
      throw new UnauthorizedException();
    }
  }

  private extractToken(request: Request): string | undefined {
    const [type, token] = request.headers.authorization?.split(' ') ?? [];
    return type === 'Bearer' ? token : undefined;
  }
}

Configuration

Parameter	Type	Default	Description
platform	string	"express"	HTTP platform: express, fastify
orm	string	"typeorm"	ORM: typeorm, prisma, drizzle, mikro-orm
validation	string	"class-validator"	Input validation library
swagger	boolean	true	Auto-generate Swagger/OpenAPI docs
cors	boolean	true	Enable CORS
global_prefix	string	"api"	URL prefix for all routes
versioning	string	"none"	API versioning: none, uri, header, media

Best Practices

1. Organize by feature modules, not layers — group controllers, services, DTOs, and entities by feature (UsersModule, OrdersModule) rather than by type (all controllers together); this improves cohesion and makes modules independently deployable.

2. Use DTOs with class-validator for input validation — define CreateUserDto classes with validation decorators (@IsEmail(), @MinLength(8)) and use ValidationPipe globally to validate all incoming requests.

3. Make services injectable and testable — use constructor-based dependency injection so services can be easily mocked in tests; avoid importing services directly.

4. Use guards for authorization, not middleware — guards have access to the execution context (which handler, which class) and can use decorators for role-based access; middleware runs before routing.

5. Enable Swagger in development — use @nestjs/swagger to auto-generate API documentation from your DTOs and controllers; this serves as living documentation that stays in sync with the code.

Common Issues

Circular dependency between modules — Two modules importing each other causes initialization errors. Use forwardRef(() => ModuleName) to break the cycle, or refactor to extract shared logic into a third module.

Validation pipe not working on nested objects — Add @Type(() => NestedDto) from class-transformer on nested DTO properties; without it, class-validator doesn't know to validate nested objects.

Service not found error despite being in providers — Check that the service is listed in the providers array of its module AND that the module is imported by the module trying to inject it. If the service needs to be shared, add it to exports as well.