NestJS Best Practices

Version 1.5.0 · 54 rules in 11 sections · generated by scripts/build-agents.ts, do not edit by hand.

How to use this file

This is an index. Each line below is one rule: what to do, why it matters, and the file with full wrong/right code examples.

1. Find the rules that match the code you are writing, reviewing, or refactoring.
2. Open the linked rule file and follow its Correct example.
3. Sections are ordered by impact. When rules conflict, the higher section wins.
4. Do not load every rule file at once. Read only the ones you need.

1. Architecture (CRITICAL)

• Avoid Circular Dependencies — Prevents startup crashes from unresolved dependencies. arch-avoid-circular-deps.md
• Organize by Feature Modules — Related code lives together, so features are easier to find and change. arch-feature-modules.md
• Use Proper Module Sharing Patterns — Prevents duplicate instances, memory leaks, and state inconsistency. arch-module-sharing.md
• Single Responsibility for Services — Smaller services are easier to test and change. arch-single-responsibility.md
• Use Event-Driven Architecture for Decoupling — Enables async processing and modularity. arch-use-events.md
• Use Repository Pattern for Data Access — Decouples business logic from database. arch-use-repository-pattern.md

2. Dependency Injection (CRITICAL)

• Avoid Service Locator Anti-Pattern — Hides dependencies and breaks testability. di-avoid-service-locator.md
• Apply Interface Segregation Principle — Reduces coupling and keeps test mocks small. di-interface-segregation.md
• Honor Liskov Substitution Principle — Ensures implementations are truly interchangeable without breaking callers. di-liskov-substitution.md
• Prefer Constructor Injection — Required for proper DI and testing. di-prefer-constructor-injection.md
• Understand Provider Scopes — Prevents data leaks and performance issues. di-scope-awareness.md
• Use Injection Tokens for Interfaces — Enables interface-based DI at runtime. di-use-interfaces-tokens.md

3. Error Handling (HIGH)

• Handle Async Errors Properly — Prevents process crashes from unhandled rejections. error-handle-async-errors.md
• Throw HTTP Exceptions from Services — Keeps controllers thin and simplifies error handling. error-throw-http-exceptions.md
• Use Exception Filters for Error Handling — Consistent, centralized error handling. error-use-exception-filters.md

4. Security (HIGH)

• Implement Secure JWT Authentication — Essential for secure APIs. security-auth-jwt.md
• Check Permissions per Record, Deny by Default — Stops users from reading or changing other users' data by changing an id in the URL. security-authorize-records.md
• Set Security Headers, a Strict CORS Policy, and CSRF Protection — Blocks clickjacking, cross-site request forgery, and reads of your API from untrusted sites. security-headers-cors-csrf.md
• Implement Rate Limiting — Protects against abuse and ensures fair resource usage. security-rate-limiting.md
• Sanitize Output to Prevent XSS — XSS vulnerabilities can compromise user sessions and data. security-sanitize-output.md
• Use Guards for Authentication and Authorization — Enforces access control before handlers execute. security-use-guards.md
• Validate All Input with DTOs and Pipes — First line of defense against attacks. security-validate-all-input.md

5. Performance (HIGH)

• Use Async Lifecycle Hooks Correctly — Improper async handling blocks application startup. perf-async-hooks.md
• Use Lazy Loading for Large Modules — Improves startup time for large applications. perf-lazy-loading.md
• Optimize Database Queries — Database queries are typically the largest source of latency. perf-optimize-database.md
• Use Caching Strategically — Dramatically reduces database load and response times. perf-use-caching.md
• Consider the Fastify Adapter, and Stay Platform-Agnostic — Faster HTTP layer for request-heavy APIs, and code that keeps working if you switch. perf-use-fastify.md

6. Testing (MEDIUM-HIGH)

• Use Supertest for E2E Testing — Validates the full request/response cycle. test-e2e-supertest.md
• Mock External Services in Tests — Ensures fast, reliable, deterministic tests. test-mock-external-services.md
• Use Testing Module for Unit Tests — Enables proper isolated testing with mocked dependencies. test-use-testing-module.md

7. Database & ORM (MEDIUM-HIGH)

• Avoid N+1 Query Problems — N+1 queries are one of the most common performance killers. db-avoid-n-plus-one.md
• Register Drizzle or Prisma Once, Through Nest Providers — One connection pool per app, clean shutdown, and transactions that really include every query. db-drizzle-prisma-integration.md
• Use Database Migrations — Enables safe, repeatable database schema changes. db-use-migrations.md
• Use Transactions for Multi-Step Operations — Ensures data consistency in multi-step operations. db-use-transactions.md

8. API Design (MEDIUM)

• Use DTOs and Serialization for API Responses — Response DTOs prevent accidental data exposure and ensure consistency. api-use-dto-serialization.md
• Use Interceptors for Cross-Cutting Concerns — Interceptors provide clean separation for cross-cutting logic. api-use-interceptors.md
• Use Pipes for Input Transformation — Pipes ensure clean, validated data reaches your handlers. api-use-pipes.md
• Use API Versioning for Breaking Changes — Versioning allows you to evolve APIs without breaking existing clients. api-versioning.md

9. Microservices (MEDIUM)

• Implement Health Checks for Microservices — Health checks enable orchestrators to manage service lifecycle. micro-use-health-checks.md
• Make Unsafe Operations Idempotent with Idempotency Keys — Client retries after a lost response no longer charge, create, or send twice. micro-use-idempotency-keys.md
• Use Message and Event Patterns Correctly — Proper patterns ensure reliable microservice communication. micro-use-patterns.md
• Use Message Queues for Background Jobs — Queues enable reliable background processing. micro-use-queues.md
• Put Timeouts, Retries, and Circuit Breakers on Calls to Other Services — One slow or failing dependency stops dragging the whole API down with it. micro-use-resilience.md

10. DevOps & Deployment (LOW-MEDIUM)

• Build Small, Non-Root Docker Images and Audit Dependencies — Smaller attack surface, clean shutdowns in containers, and known-vulnerable packages caught before release. devops-docker-and-dependencies.md
• Implement Graceful Shutdown — Proper shutdown handling ensures zero-downtime deployments. devops-graceful-shutdown.md
• Use ConfigModule for Environment Configuration — Proper configuration prevents deployment failures. devops-use-config-module.md
• Use Structured Logging — Structured logging enables effective debugging and monitoring. devops-use-logging.md
• Trace Requests with OpenTelemetry — Shows where a slow or failed request spent its time, across services and the database. devops-use-tracing.md

11. Domain-Driven Design & Modular Monolith (MEDIUM-HIGH)

Opt-in. Use only for modular monoliths with real business rules. Skip for simple CRUD apps.

• One Repository per Aggregate, Interface in Domain — Aggregates are always loaded and saved whole, so their rules cannot be bypassed. ddd-aggregate-repository.md
• One Module per Bounded Context with Layers — Keeps business areas independent so they can change, scale, or split out on their own. ddd-bounded-context-modules.md
• Split Writes and Reads with CQRS — Writes stay safe through aggregates while reads stay fast and shaped for the screen. ddd-cqrs.md
• Modules Talk Only Through a Public Contract or Integration Events — Stops hidden coupling between modules so one module can change or move out without breaking others. ddd-module-public-api.md
• Keep Business Rules in a Rich Domain Model, Separate from ORM Entities — Rules live in one place and cannot be skipped; domain tests run without a database. ddd-rich-domain-model.md
• Publish Integration Events with a Transactional Outbox — No lost or phantom events when the app crashes between saving data and publishing. ddd-transactional-outbox.md

Learn skill (separate)

skills/nestjs-learn teaches NestJS by having the owner type their own app: what next, write the lesson, done, check, and ship it. It is not part of this index; references/check.md maps every rule above, and a test fails if a rule is missing there. Tests: node --test skills/nestjs-learn/scripts/learn.test.mjs. Token budgets: node scripts/check-tokens.mjs.

Modular monolith skill (separate)

skills/nestjs-modular-monolith sets up the layout from section 11 (layers, contracts/, public index.ts) and enforces it with dependency-cruiser, proven by a self-test. Keep its references/structure.md and the ddd-* rules teaching the same structure. Tests: node --test skills/nestjs-modular-monolith/scripts/modular-monolith.test.mjs (needs npm install in scripts/).

Contributing

Edit or add files in skills/nestjs-best-practices/rules/ (see _template.md and _sections.md), then run npm run build in scripts/ to regenerate this file.

References

• https://docs.nestjs.com
• https://github.com/nestjs/nest
• https://typeorm.io
• https://github.com/typestack/class-validator
• https://github.com/goldbergyoni/nodebestpractices