nestjs-best-practices

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.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