1---
2name: nestjs-best-practices
3description: NestJS best practices and architecture patterns for building production-ready applications. This skill should be used when writing, reviewing, or refactoring NestJS code to ensure proper patterns for modules, dependency injection, security, and performance.
4license: MIT
5metadata:
6  author: Kadajett
7  version: "1.1.0"
8---
9 
10# NestJS Best Practices
11 
12Comprehensive best practices guide for NestJS applications. Contains 40 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.
13 
14## When to Apply
15 
16Reference these guidelines when:
17 
18- Writing new NestJS modules, controllers, or services
19- Implementing authentication and authorization
20- Reviewing code for architecture and security issues
21- Refactoring existing NestJS codebases
22- Optimizing performance or database queries
23- Building microservices architectures
24 
25## Rule Categories by Priority
26 
27| Priority | Category | Impact | Prefix |
28|----------|----------|--------|--------|
29| 1 | Architecture | CRITICAL | `arch-` |
30| 2 | Dependency Injection | CRITICAL | `di-` |
31| 3 | Error Handling | HIGH | `error-` |
32| 4 | Security | HIGH | `security-` |
33| 5 | Performance | HIGH | `perf-` |
34| 6 | Testing | MEDIUM-HIGH | `test-` |
35| 7 | Database & ORM | MEDIUM-HIGH | `db-` |
36| 8 | API Design | MEDIUM | `api-` |
37| 9 | Microservices | MEDIUM | `micro-` |
38| 10 | DevOps & Deployment | LOW-MEDIUM | `devops-` |
39 
40## Quick Reference
41 
42### 1. Architecture (CRITICAL)
43 
44- `arch-avoid-circular-deps` - Avoid circular module dependencies
45- `arch-feature-modules` - Organize by feature, not technical layer
46- `arch-module-sharing` - Proper module exports/imports, avoid duplicate providers
47- `arch-single-responsibility` - Focused services over "god services"
48- `arch-use-repository-pattern` - Abstract database logic for testability
49- `arch-use-events` - Event-driven architecture for decoupling
50 
51### 2. Dependency Injection (CRITICAL)
52 
53- `di-avoid-service-locator` - Avoid service locator anti-pattern
54- `di-interface-segregation` - Interface Segregation Principle (ISP)
55- `di-liskov-substitution` - Liskov Substitution Principle (LSP)
56- `di-prefer-constructor-injection` - Constructor over property injection
57- `di-scope-awareness` - Understand singleton/request/transient scopes
58- `di-use-interfaces-tokens` - Use injection tokens for interfaces
59 
60### 3. Error Handling (HIGH)
61 
62- `error-use-exception-filters` - Centralized exception handling
63- `error-throw-http-exceptions` - Use NestJS HTTP exceptions
64- `error-handle-async-errors` - Handle async errors properly
65 
66### 4. Security (HIGH)
67 
68- `security-auth-jwt` - Secure JWT authentication
69- `security-validate-all-input` - Validate with class-validator
70- `security-use-guards` - Authentication and authorization guards
71- `security-sanitize-output` - Prevent XSS attacks
72- `security-rate-limiting` - Implement rate limiting
73 
74### 5. Performance (HIGH)
75 
76- `perf-async-hooks` - Proper async lifecycle hooks
77- `perf-use-caching` - Implement caching strategies
78- `perf-optimize-database` - Optimize database queries
79- `perf-lazy-loading` - Lazy load modules for faster startup
80 
81### 6. Testing (MEDIUM-HIGH)
82 
83- `test-use-testing-module` - Use NestJS testing utilities
84- `test-e2e-supertest` - E2E testing with Supertest
85- `test-mock-external-services` - Mock external dependencies
86 
87### 7. Database & ORM (MEDIUM-HIGH)
88 
89- `db-use-transactions` - Transaction management
90- `db-avoid-n-plus-one` - Avoid N+1 query problems
91- `db-use-migrations` - Use migrations for schema changes
92 
93### 8. API Design (MEDIUM)
94 
95- `api-use-dto-serialization` - DTO and response serialization
96- `api-use-interceptors` - Cross-cutting concerns
97- `api-versioning` - API versioning strategies
98- `api-use-pipes` - Input transformation with pipes
99 
100### 9. Microservices (MEDIUM)
101 
102- `micro-use-patterns` - Message and event patterns
103- `micro-use-health-checks` - Health checks for orchestration
104- `micro-use-queues` - Background job processing
105 
106### 10. DevOps & Deployment (LOW-MEDIUM)
107 
108- `devops-use-config-module` - Environment configuration
109- `devops-use-logging` - Structured logging
110- `devops-graceful-shutdown` - Zero-downtime deployments
111 
112## How to Use
113 
114Read individual rule files for detailed explanations and code examples:
115 
116```
117rules/arch-avoid-circular-deps.md
118rules/security-validate-all-input.md
119rules/_sections.md
120```
121 
122Each rule file contains:
123- Brief explanation of why it matters
124- Incorrect code example with explanation
125- Correct code example with explanation
126- Additional context and references
127 
128## Full Compiled Document
129 
130For the complete guide with all rules expanded: `AGENTS.md`
131