NestJS Best Practices
Conventions for NestJS applications using configurable dynamic modules, custom domain exceptions, Mongoose, and feature-based module organization.
When to Apply
- Writing new NestJS modules, services, or controllers
- Refactoring existing NestJS code to follow these patterns
- Implementing authentication, validation, or data access
- Organizing code by feature (not by technical layer)
Rule Categories
Architecture
- arch-dynamic-modules — Use ConfigurableModuleBuilder,
*-module-definition.ts, andstatic register()for dynamic modules. See rules/arch-dynamic-modules.md. - arch-feature-modules — Organize by feature under
src/modules/<feature>/with*.module.ts,*.module-definition.ts, andindex.ts. See rules/arch-feature-modules.md.
Error Handling
- error-custom-exceptions — Extend AbstractException with
codeandmetadata; throw domain exceptions from services. See rules/error-custom-exceptions.md.
Database & Data Access
- db-mongoose-data-access — Inject Mongoose
Connectionvia custom decorator (e.g.@InjectPrimaryMongoose()), useconnection.model(Schema.name). See rules/db-mongoose-data-access.md.
Dependency Injection
- di-constructor-injection — Use
@Injectable()and constructor injection withprivate readonlyfor all dependencies. See rules/di-constructor-injection.md.
API & Validation
- api-dto-validation — Define DTOs with
class-validatordecorators (@IsEmail(),@IsString(), etc.) for input validation. See rules/api-dto-validation.md.
Security
- security-guards — Use Throttler, JWT, and TOTP guards; configure ThrottlerModule with Redis storage where needed. See rules/security-guards.md.
How to Use
Read individual rule files under rules/ for incorrect vs correct examples and detailed guidance.
For the full compiled document with all rules in one file: AGENTS.md (generated by scripts/build-agents.ts).