giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-typescript/skills/nestjs-best-practices
nestjs-best-practices
VerifiedProvides comprehensive NestJS best practices including modular architecture, dependency injection scoping, exception filters, DTO validation with class-validator, and Drizzle ORM integration. Use when designing NestJS modules, implementing providers, creating exception filters, validating DTOs, or integrating Drizzle ORM within NestJS applications.
NestJS Best Practices
Overview
Grounded in the Official NestJS Documentation, this skill enforces modular architecture, dependency injection scoping, exception filters, DTO validation with class-validator, and Drizzle ORM integration patterns.
When to Use
- Designing/refactoring NestJS modules or dependency injection
- Creating exception filters, validating DTOs, or integrating Drizzle ORM
- Reviewing code for anti-patterns or onboarding to a NestJS codebase
Instructions
1. Modular Architecture
Follow strict module encapsulation. Each domain feature should be its own @Module():
- Export only what other modules need — keep internal providers private
- Use
forwardRef()only as a last resort for circular dependencies; prefer restructuring - Group related controllers, services, and repositories within the same module
- Use a
SharedModulefor cross-cutting concerns (logging, configuration, caching)
See references/arch-module-boundaries.md for enforcement rules.
2. Dependency Injection
Choose the correct provider scope based on use case:
| Scope | Lifecycle | Use Case |
|---|---|---|
DEFAULT | Singleton (shared) | Stateless services, repositories |
REQUEST | Per-request instance | Request-scoped data (tenant, user context) |
TRANSIENT | New instance per injection | Stateful utilities, per-consumer caches |
- Default to
DEFAULTscope — only useREQUESTorTRANSIENTwhen justified - Use constructor injection exclusively — avoid property injection
- Register custom providers with
useClass,useValue,useFactory, oruseExisting
See references/di-provider-scoping.md for enforcement rules.
3. Request Lifecycle
Understand and respect the NestJS request processing pipeline:
Middleware → Guards → Interceptors (before) → Pipes → Route Handler → Interceptors (after) → Exception Filters
- Middleware: Cross-cutting concerns (logging, CORS, body parsing)
- Guards: Authorization and authentication checks (return
true/false) - Interceptors: Transform response data, add caching, measure timing
- Pipes: Validate and transform input parameters
- Exception Filters: Catch and format error responses
4. Error Handling
Standardize error responses across the application:
- Extend
HttpExceptionfor HTTP-specific errors - Create domain-specific exception classes (e.g.,
OrderNotFoundException) - Implement a global
ExceptionFilterfor consistent error formatting - Use the Result pattern for expected business logic failures
- Never silently swallow exceptions
See references/error-exception-filters.md for enforcement rules.
5. Validation
Enforce input validation at the API boundary:
- Enable
ValidationPipeglobally withtransform: trueandwhitelist: true - Decorate all DTO properties with
class-validatordecorators - Use
class-transformerfor type coercion (@Type(),@Transform()) - Create separate DTOs for Create, Update, and Response operations
- Never trust raw user input — validate everything
See references/api-validation-dto.md for enforcement rules.
6. Database Patterns (Drizzle ORM)
Integrate Drizzle ORM following NestJS provider conventions:
- Wrap the Drizzle client in an injectable provider
- Use the Repository pattern for data access encapsulation
- Define schemas in dedicated schema files per domain module
- Use transactions for multi-step operations
- Keep database logic out of controllers
See references/db-drizzle-patterns.md for enforcement rules.
Best Practices
| Area | Do | Don't |
|---|---|---|
| Modules | One module per domain feature | Dump everything in AppModule |
| DI Scoping | Default to singleton scope | Use REQUEST scope without justification |
| Error Handling | Custom exception filters + domain errors | Bare try/catch with console.log |
| Validation | Global ValidationPipe + DTO decorators | Manual if checks in controllers |
| Database | Repository pattern with injected client | Direct DB queries in controllers |
| Testing | Unit test services, e2e test controllers | Skip tests or test implementation details |
| Configuration | @nestjs/config with typed schemas | Hardcode values or use process.env |
Examples
Example: New Domain Module with Validation
When building a "Product" feature, follow this workflow:
1. Create the module with proper encapsulation:
// product/product.module.ts
@Module({
imports: [DatabaseModule],
controllers: [ProductController],
providers: [ProductService, ProductRepository],
exports: [ProductService], // Only export what others need
})
export class ProductModule {}
2. Create validated DTOs:
// product/dto/create-product.dto.ts
import { IsString, IsNumber, IsPositive, MaxLength } from 'class-validator';
export class CreateProductDto {
@IsString() @MaxLength(255) readonly name: string;
@IsNumber() @IsPositive() readonly price: number;
}
3. Service with error handling:
@Injectable()
export class ProductService {
constructor(private readonly productRepository: ProductRepository) {}
async findById(id: string): Promise<Product> {
const product = await this.productRepository.findById(id);
if (!product) throw new ProductNotFoundException(id);
return product;
}
}
4. Verify module registration:
# Check module is imported in AppModule
grep -r "ProductModule" src/app.module.ts
# Run e2e to confirm exports work
npx jest --testPathPattern="product"
Constraints and Warnings
- Do not mix scopes without justification —
REQUEST-scoped providers cascade to all dependents - Never access database directly from controllers — always go through service and repository layers
- Avoid
forwardRef()— restructure modules to eliminate circular dependencies - Do not skip
ValidationPipe— always validate at the API boundary with DTOs - Never hardcode secrets — use
@nestjs/configwith environment variables - Keep modules focused — one domain feature per module, avoid "god modules"
References
references/architecture.md— Deep-dive into NestJS architectural patternsreferences/— Individual enforcement rules with correct/incorrect examplesassets/templates/— Starter templates for common NestJS components
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |