SKILL.md
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
Reference these guidelines when:
- Writing new NestJS modules, controllers, or services
- Implementing authentication and authorization
- Reviewing code for architecture and security issues
- Refactoring existing NestJS codebases
- Optimizing performance or database queries
- Building microservices architectures
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.mdEach 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