nestjs-best-practices

name	nestjs-best-practices
description	NestJS architecture patterns and best practices. TRIGGER when: planning or implementing NestJS features (modules, controllers, services, etc), designing modules, implementing auth/security, or writing NestJS tests. DO NOT TRIGGER when: only reading NestJS code without intent to modify, working on frontend, or asking general TypeScript questions.
license	MIT
metadata	{"author":"Kadajett","version":"1.1.0"}

NestJS Best Practices

Comprehensive best practices guide for NestJS applications. Contains 40 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Apply these guidelines during planning and implementation of NestJS features:

• Planning phase: When designing module architecture, defining service boundaries, or choosing patterns for a new feature in nestjs-project/
• Implementation phase: When writing or modifying controllers, services, guards, pipes, interceptors, entities, or repositories
• Auth & Security: When implementing authentication, authorization, guards, or input validation
• Database: When creating entities, repositories, migrations, or optimizing queries with TypeORM
• Testing: When writing unit or e2e tests for NestJS modules
• Code Review: When reviewing NestJS code for architecture, security, or performance issues

When NOT to Apply

Do not load this skill when:

• Only reading or exploring NestJS code to understand it, without intent to plan or implement changes
• Working on frontend code (Next.js, React components) even if it consumes the NestJS API
• Answering general TypeScript or Node.js questions that don't involve NestJS framework patterns
• Discussing high-level project requirements without NestJS implementation scope

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Architecture	CRITICAL	arch-
2	Dependency Injection	CRITICAL	di-
3	Error Handling	HIGH	error-
4	Security	HIGH	security-
5	Performance	HIGH	perf-
6	Testing	MEDIUM-HIGH	test-
7	Database & ORM	MEDIUM-HIGH	db-
8	API Design	MEDIUM	api-
9	Microservices	MEDIUM	micro-
10	DevOps & Deployment	LOW-MEDIUM	devops-

Quick Reference

1. Architecture (CRITICAL)

• arch-avoid-circular-deps - Avoid circular module dependencies
• arch-feature-modules - Organize by feature, not technical layer
• arch-module-sharing - Proper module exports/imports, avoid duplicate providers
• arch-single-responsibility - Focused services over "god services"
• arch-use-repository-pattern - Abstract database logic for testability
• arch-use-events - Event-driven architecture for decoupling

2. Dependency Injection (CRITICAL)

• di-avoid-service-locator - Avoid service locator anti-pattern
• di-interface-segregation - Interface Segregation Principle (ISP)
• di-liskov-substitution - Liskov Substitution Principle (LSP)
• di-prefer-constructor-injection - Constructor over property injection
• di-scope-awareness - Understand singleton/request/transient scopes
• di-use-interfaces-tokens - Use injection tokens for interfaces

3. Error Handling (HIGH)

• error-use-exception-filters - Centralized exception handling
• error-throw-http-exceptions - Use NestJS HTTP exceptions
• error-handle-async-errors - Handle async errors properly

4. Security (HIGH)

• security-auth-jwt - Secure JWT authentication
• security-validate-all-input - Validate with class-validator
• security-use-guards - Authentication and authorization guards
• security-sanitize-output - Prevent XSS attacks
• security-rate-limiting - Implement rate limiting

5. Performance (HIGH)

• perf-async-hooks - Proper async lifecycle hooks
• perf-use-caching - Implement caching strategies
• perf-optimize-database - Optimize database queries
• perf-lazy-loading - Lazy load modules for faster startup

6. Testing (MEDIUM-HIGH)

• test-use-testing-module - Use NestJS testing utilities
• test-e2e-supertest - E2E testing with Supertest
• test-mock-external-services - Mock external dependencies

7. Database & ORM (MEDIUM-HIGH)

• db-use-transactions - Transaction management
• db-avoid-n-plus-one - Avoid N+1 query problems
• db-use-migrations - Use migrations for schema changes

8. API Design (MEDIUM)

• api-use-dto-serialization - DTO and response serialization
• api-use-interceptors - Cross-cutting concerns
• api-versioning - API versioning strategies
• api-use-pipes - Input transformation with pipes

9. Microservices (MEDIUM)

• micro-use-patterns - Message and event patterns
• micro-use-health-checks - Health checks for orchestration
• micro-use-queues - Background job processing

10. DevOps & Deployment (LOW-MEDIUM)

• devops-use-config-module - Environment configuration
• devops-use-logging - Structured logging
• devops-graceful-shutdown - Zero-downtime deployments

How to Use

Read individual rule files for detailed explanations and code examples:

rules/arch-avoid-circular-deps.md
rules/security-validate-all-input.md
rules/_sections.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md