architecting-nestjs-modules

name	architecting-nestjs-modules
description	Designs NestJS feature modules with clean dependency boundaries, provider scopes, and dynamic modules. Use when adding a new feature module, splitting a monolithic AppModule, or fixing tangled imports between modules.
license	MIT

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

@Module({
  controllers: [UserController],
  providers: [
    CreateUserUseCase,
    { provide: 'UserRepository', useClass: TypeOrmUserRepository },
  ],
  exports: [CreateUserUseCase],
})
export class UserModule {}

Dynamic Module Example

@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

// Clean module boundary
@Module({ controllers: [OrderController], providers: [OrderService], exports: [OrderService] })
export class OrderModule {}

Examples — Don't

// ❌ 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 for full patterns.