architecting-nestjs-modules

# Architecting NestJS Modules ## When to use - Adding a new feature module - Splitting a monolithic `AppModule` - Fixing tangled imports between modules ## Core rules 1. Feature modules own their domain, application, infrastructure layers 2. Providers default to `Scope.DEFAULT` (singleton), use `Scope.REQUEST` only when needed 3. Export only what other modules need (don't export everything) 4. Dynamic modules for configurable features (database, cache) 5. No cross-feature imports; use shared contracts ## Reference shape (TypeScript) ### Feature Module ```typescript @Module({ controllers: [UserController], providers: [ CreateUserUseCase, { provide: 'UserRepository', useClass: TypeOrmUserRepository }, ], exports: [CreateUserUseCase], }) export class UserModule {} ``` ### Dynamic Module Example ```typescript @Module({}) export class DatabaseModule { static register(config: DatabaseConfig): DynamicModule { return { module: DatabaseModule, providers: [ { provide: 'DATABASE_CONFIG', useValue: config }, { provide: DataSource, useFactory: () => new DataSource(config).initialize() }, ], exports: [DataSource], }; } } ``` ## Examples — Do ```typescript // Clean module boundary @Module({ controllers: [OrderController], providers: [OrderService], exports: [OrderService] }) export class OrderModule {} ``` ## Examples — Don't ```typescript // ❌ Monolithic AppModule @Module({ controllers: [UserController, OrderController, ProductController], providers: [...] }) export class AppModule {} ``` ## Checklist - [ ] Feature modules with own layers - [ ] Providers with appropriate scopes - [ ] Only necessary exports - [ ] No cross-feature imports See [reference/module-patterns.md](./reference/module-patterns.md) for full patterns.