developing-nestjs-recipe

NestJS Development

NestJS v11.x framework patterns + hexagonal architecture compliance

Quick Reference

// Module + DI
@Module({ imports: [], providers: [], controllers: [], exports: [] })
export class UserModule {}

@Injectable()
export class UserService {
  constructor(@Inject('UserRepo') private repo: UserRepo) {}
}

// Controller (inbound ONLY)
@Controller('users')
export class UserController {
  @Get(':id')
  findOne(@Param('id') id: string) {}
}

// Guards
@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {}
}

// Validation
export class CreateUserDto {
  @IsString() @IsNotEmpty() name: string
}

// Scheduling (inbound ONLY)
@Injectable()
export class ReportScheduler {
  @Cron('0 0 * * *') async generate() {}
}

When to Use

@Module → DI | @Injectable → services | @Controller → HTTP | @Cron → scheduling
@UseGuards → auth | @UsePipes → validation | @Inject → dependencies
Guards → authorize | Interceptors → transform | Pipes → validate | Filters → errors
Decorators → metadata | Lifecycle hooks → init/destroy | Testing → TestingModule

Navigation

Abbreviations: IN = src/inbound/ | OUT = src/outbound/ | SVC = src/service/ | DOM = src/domain/

Topic	File	Key Constraints
Fundamentals
Modules & DI	modules-di.md	No circular deps, proper providers
Lifecycle Hooks	lifecycle-hooks.md	No async in constructor
Controllers	controllers.md	ONLY in IN/
Middleware	middleware.md	Order matters, proper next()
Custom Decorators	custom-decorators.md	Type safety, metadata
HTTP Module	http-module.md	HttpService ONLY in OUT/
API Versioning	api-versioning.md	URI/Header/MediaType versioning
Circular Dependencies	circular-dependencies.md	Use forwardRef OR refactor
Global Configuration	global-configuration.md	Global prefix, shutdown hooks
Body Parser	body-parser.md	Size limits, raw body
Request Lifecycle	request-lifecycle.md	Middleware→Guards→Pipes flow
Request/Response
Guards	guards.md	Return boolean, execution order
Interceptors	interceptors.md	Observable transform, cleanup
Pipes	pipes.md	DTO validation, transformation
Filters	filters.md	Exception handling, error mapping
Validation	validation.md	class-validator decorators
Transformation	transformation.md	class-transformer, @Exclude
Mapped Types	mapped-types.md	PartialType, PickType, OmitType
File Upload	file-upload.md	Multer, file validation
Scheduling & Async
Scheduling	scheduling.md	@Cron ONLY in IN/
Queues	queues.md	@Processor ONLY in IN/
Events	events.md	@OnEvent ONLY in IN/
Security
Guards & Auth	guards-auth.md	JWT, Passport strategies
Authorization	authorization.md	RBAC, ABAC, permissions
Rate Limiting	rate-limiting.md	@Throttle on login/signup
CORS & Helmet	cors-helmet.md	Security headers, no wildcards
Cookies & Sessions	cookies-sessions.md	httpOnly, secure, sameSite
Validation Security	validation-security.md	SQL injection, XSS prevention
Configuration
Configuration	config.md	Typed config, NO process.env
Dynamic Modules	dynamic-modules.md	forRoot, forRootAsync
Environment	environment.md	Multi-env, .env files
Database
TypeORM	typeorm.md	ONLY in OUT/
Prisma	prisma.md	ONLY in OUT/
Mongoose	mongoose.md	ONLY in OUT/
Transactions	transactions.md	Rollback, release in finally
Testing
Unit Testing	unit.md	TestingModule, mock dependencies
Integration Testing	integration.md	Module integration
E2E Testing	e2e.md	Supertest, full app
Testcontainers	testcontainers.md	Docker in tests, cleanup
Mocking Strategies	mocking-strategies.md	jest.fn(), spies
HTTP Mocking	http-mocking.md	Mock HttpService, axios
Performance Testing	performance-testing.md	Load tests, benchmarks
Microservices
Patterns	patterns.md	@MessagePattern in IN/
Transports	transports.md	Redis, NATS, Kafka, gRPC
Hybrid Apps	hybrid-apps.md	HTTP + Microservices
WebSockets
Gateways	gateways.md	@WebSocketGateway in IN/
Adapters	adapters.md	Socket.io vs ws
GraphQL
Resolvers	resolvers.md	@Resolver in IN/
Schema	schema.md	Code-first vs schema-first
Subscriptions	subscriptions.md	Real-time GraphQL
Observability
Logging	logging.md	Logger service, NO console.log
Metrics	metrics.md	Histograms, counters
Tracing	tracing.md	OpenTelemetry, spans
Health Checks	health-checks.md	Terminus, liveness/readiness
Caching & Performance
Caching	caching.md	CacheModule, Redis, TTL
Compression	compression.md	gzip middleware
Streaming	streaming.md	Response streaming, SSE
API Documentation
Swagger	swagger.md	@ApiTags, @ApiOperation
Compodoc	compodoc.md	Code documentation
Deployment
Docker	docker.md	Multi-stage builds
Kubernetes	kubernetes.md	Health checks, probes
Production	production.md	PM2, clustering
Production Best Practices	production-best-practices.md	Security, performance checklist
CLI
Generators	generators.md	nest generate commands
Build & Deploy	build-deploy.md	Build optimization
Advanced
Scopes	scopes.md	DEFAULT vs REQUEST vs TRANSIENT
Advanced DI	advanced-di.md	@Optional, @Self, @SkipSelf
Module Reference	module-reference.md	ModuleRef, lazy loading
Lazy Loading	lazy-loading.md	Lazy module loading
Execution Context	execution-context.md	ArgumentsHost, switching
Platform Agnostic	platform-agnostic.md	Express vs Fastify
Standalone Apps	standalone-apps.md	CLI tools, workers
Async Local Storage	async-local-storage.md	Request context, correlation IDs
Examples
Hexagonal NestJS	hexagonal-nestjs.md	Real patterns from cpl-config-distributer
Auth Flow	auth-flow.md	Complete authentication example
Rate-Limited API	rate-limited-api.md	Auth + Rate limiting example

Master Validation Workflow

Run after any NestJS code generation or review.

Execution Phases

Phase	Action
1. Scan	Identify all NestJS patterns in codebase
2. Validate	Run ALL topic-specific validations
3. Report	✓ ALL pass → Done | ✗ ANY fail → REJECT with full report
4. Fix	Violations → Fix → Re-validate

Validation Categories (76 Topics)

Run ALL validations for complete compliance

#	Category	Critical Rules	Reference
1	Module Structure	No circular deps, proper @Module	modules-di.md#validation
2	Lifecycle Hooks	No async in constructor	lifecycle-hooks.md#validation
3	Controller Placement	ONLY in IN/	controllers.md#validation
4	Middleware	Call next(), proper order	middleware.md#validation
5	Custom Decorators	Type safety, metadata	custom-decorators.md#validation
6	Guard Patterns	Return boolean, execution order	guards.md#validation
7	Interceptor Patterns	Observable return, cleanup	interceptors.md#validation
8	Pipe Usage	All DTOs validated	pipes.md#validation
9	Exception Filters	Error handling, format	filters.md#validation
10	DTO Validation	class-validator decorators	validation.md#validation
11	Transformation	@Exclude sensitive fields	transformation.md#validation
12	File Upload	File size, type validation	file-upload.md#validation
13	Scheduler Placement	@Cron ONLY in IN/	scheduling.md#validation
14	Queue Processors	@Processor ONLY in IN/	queues.md#validation
15	Event Listeners	@OnEvent ONLY in IN/	events.md#validation
16	Auth Guards	JWT secrets, guard on routes	guards-auth.md#validation
17	Authorization	RBAC/ABAC on sensitive routes	authorization.md#validation
18	Rate Limiting	Strict limits on login/signup	rate-limiting.md#validation
19	CORS & Security	No wildcard origins in prod	cors-helmet.md#validation
20	Validation Security	SQL injection, XSS prevention	validation-security.md#validation
21	Configuration	NO process.env, typed config	config.md#validation
22	Dynamic Modules	forRoot once, DynamicModule	dynamic-modules.md#validation
23	Environment	.env files, no secrets in git	environment.md#validation
24	TypeORM	Repositories in OUT/	typeorm.md#validation
25	Prisma	PrismaService in OUT/	prisma.md#validation
26	Mongoose	@Schema in OUT/	mongoose.md#validation
27	Transactions	Rollback, release in finally	transactions.md#validation
28	Unit Testing	TestingModule, mock all deps	unit.md#validation
29	Integration Testing	Module scope, real deps	integration.md#validation
30	E2E Testing	App init/close, supertest	e2e.md#validation
31	Testcontainers	Container cleanup	testcontainers.md#validation
32	Mocking Strategies	jest.fn(), clear mocks	mocking-strategies.md#validation
33	Microservice Patterns	@MessagePattern in IN/	patterns.md#validation
34	Transports	Config from env, error handling	transports.md#validation
35	Hybrid Apps	startAllMicroservices()	hybrid-apps.md#validation
36	WebSocket Gateways	@WebSocketGateway in IN/	gateways.md#validation
37	WS Adapters	Single adapter choice	adapters.md#validation
38	GraphQL Resolvers	@Resolver in IN/	resolvers.md#validation
39	GraphQL Schema	@Field decorators, type match	schema.md#validation
40	GraphQL Subscriptions	@Subscription in IN/	subscriptions.md#validation
41	Logging	Logger service, NO console.log	logging.md#validation
42	Metrics	Histograms in OnModuleInit	metrics.md#validation
43	Tracing	Span end in finally	tracing.md#validation
44	Caching	TTL configured, no sensitive data	caching.md#validation
45	Compression	Middleware before routes	compression.md#validation
46	Streaming	Stream cleanup on error	streaming.md#validation
47	Swagger	@ApiTags on controllers	swagger.md#validation
48	Compodoc	JSDoc on public methods	compodoc.md#validation
49	Docker	Multi-stage, non-root user	docker.md#validation
50	Kubernetes	Health/readiness probes	kubernetes.md#validation
51	Production	Graceful shutdown, no debug	production.md#validation
52	CLI Generators	Generated files in correct layers	generators.md#validation
53	Build & Deploy	Source maps disabled in prod	build-deploy.md#validation
54	Scopes	DEFAULT unless needed	scopes.md#validation
55	Module Reference	Use DI not ModuleRef	module-reference.md#validation
56	Execution Context	Use switchToHttp()	execution-context.md#validation
57	Platform Agnostic	Use NestJS abstractions	platform-agnostic.md#validation
58	Standalone Apps	Call app.close()	standalone-apps.md#validation
59	HTTP Module	HttpService in OUT/	http-module.md#validation
60	Mapped Types	PickType with 'as const'	mapped-types.md#validation
61	API Versioning	Versioning type configured	api-versioning.md#validation
62	Circular Dependencies	Eliminate or use forwardRef	circular-dependencies.md#validation
63	Health Checks	Health controller in IN/	health-checks.md#validation
64	Cookies & Sessions	httpOnly, secure, sameSite	cookies-sessions.md#validation
65	Global Configuration	Config before listen()	global-configuration.md#validation
66	Advanced DI	@Optional with undefined check	advanced-di.md#validation
67	Request Lifecycle	Auth guard first	request-lifecycle.md#validation
68	HTTP Mocking	Mock HttpService in tests	http-mocking.md#validation
69	Body Parser	Body size limits configured	body-parser.md#validation
70	Performance Testing	Load tests configured	performance-testing.md#validation
71	Async Local Storage	Context initialized	async-local-storage.md#validation
72	Production Best Practices	Checklist complete	production-best-practices.md#validation
73	Lazy Loading	Lazy load rarely used modules	lazy-loading.md#validation
74	GraphQL Schema	@Field decorators present	schema.md#validation
75	WS Adapters	Single adapter choice	adapters.md#validation
76	Microservice Transports	Connection strings from env	transports.md#validation

Output Format

{
  "discipline": "nestjs",
  "timestamp": "ISO8601",
  "modules": {"violations": [], "status": "pass"},
  "lifecycle": {"violations": [], "status": "pass"},
  "controllers": {"violations": [], "status": "pass"},
  "middleware": {"violations": [], "status": "pass"},
  "custom_decorators": {"violations": [], "status": "pass"},
  "guards": {"violations": [], "status": "pass"},
  "interceptors": {"violations": [], "status": "pass"},
  "pipes": {"violations": [], "status": "pass"},
  "filters": {"violations": [], "status": "pass"},
  "validation": {"violations": [], "status": "pass"},
  "scheduling": {"violations": [], "status": "pass"},
  "queues": {"violations": [], "status": "pass"},
  "events": {"violations": [], "status": "pass"},
  "auth_guards": {"violations": [], "status": "pass"},
  "rate_limiting": {"violations": [], "status": "pass"},
  "cors_security": {"violations": [], "status": "pass"},
  "configuration": {"violations": [], "status": "pass"},
  "dynamic_modules": {"violations": [], "status": "pass"},
  "typeorm": {"violations": [], "status": "pass"},
  "transactions": {"violations": [], "status": "pass"},
  "unit_testing": {"violations": [], "status": "pass"},
  "e2e_testing": {"violations": [], "status": "pass"},
  "microservices": {"violations": [], "status": "pass"},
  "websockets": {"violations": [], "status": "pass"},
  "logging": {"violations": [], "status": "pass"},
  "metrics": {"violations": [], "status": "pass"},
  "caching": {"violations": [], "status": "pass"},
  "scopes": {"violations": [], "status": "pass"},
  "summary": {"critical": 0, "errors": 0, "warnings": 0}
}

Review code → Gather evidence → Cite file:line
NOT: Re-execute OR invent violations

Re-validation required after fixes. Repeat until ALL checks pass.

Hexagonal Architecture Integration

Abbreviations: IN = src/inbound/ | OUT = src/outbound/ | SVC = src/service/ | DOM = src/domain/

NestJS Concept	Hexagonal Layer	Constraint
@Controller	Inbound	HTTP adapters → IN/http/
@Cron/@Schedule	Inbound	Schedulers → IN/schedulers/
@MessagePattern	Inbound	Message handlers → IN/messages/
@Injectable (service)	Service	Business logic → SVC/
@Injectable (adapter)	Outbound	Infrastructure → OUT/
Domain entities	Domain	Pure logic → DOM/

Placement rules:

Pattern	Layer	Violation
@Controller	IN/ ONLY	OUT/SVC/DOM → REJECT
@Cron/@Schedule	IN/ ONLY	OUT/SVC/DOM → REJECT
@MessagePattern	IN/ ONLY	OUT/SVC/DOM → REJECT
@Injectable (service)	SVC/ ONLY	IN/OUT/DOM → REJECT
@Injectable (adapter)	OUT/ ONLY	IN/SVC/DOM → REJECT
Domain entities	DOM/ ONLY	IN/OUT/SVC → REJECT

Version

NestJS v11.1.6 patterns. Check package.json for actual version.

Reference

See topic-specific files for detailed patterns and validation rules.