Dynamic modules are modules that can be configured when imported — instead of a static @Module({...}), they expose static methods (conventionally forRoot and forFeature) that return a module configured with the arguments you pass. This is how configurable, reusable modules (config, database, JWT) accept options.
A static module is fixed — but reusable modules (DatabaseModule, ConfigModule,
JwtModule) need to be CONFIGURED per app (connection URL, secret, options).
Dynamic modules let a module accept configuration at import time.
@Module({
imports: [
ConfigModule.forRoot({ isGlobal: true }), // ← forRoot with options
TypeOrmModule.forRoot({ type: "postgres", url: ... }), // ← configured at import
JwtModule.register({ secret: process.env.SECRET }), // ← register variant
TypeOrmModule.forFeature([User, Post]), // ← forFeature for specifics
],
})
export class AppModule {}
The .forRoot()/.register()/.forFeature() calls you see when importing modules are dynamic-module methods accepting configuration.
forRoot() → configure the module ONCE, globally (the connection, the secret, core setup)
called in the root/app module a single time
forFeature() → register feature-specific pieces in each feature module that needs them
(e.g. TypeOrmModule.forFeature([User]) registers entities per module)
The convention: forRoot for global/one-time configuration; forFeature for per-feature registration that you call in multiple modules.
@Module({})
export class StorageModule {
static forRoot(options: StorageOptions): DynamicModule {
return { // returns a configured module
module: StorageModule,
providers: [
{ provide: "STORAGE_OPTIONS", useValue: options }, // inject the passed options
StorageService,
],
exports: [StorageService],
global: true, // optionally make it global
};
}
}
// usage: StorageModule.forRoot({ bucket: "my-bucket", region: "us-east-1" })
The static method returns a DynamicModule object (module + providers + exports), wiring the passed options into the module's providers (often via an injection token).
// configure using OTHER injected dependencies (e.g. ConfigService) — async/factory
StorageModule.forRootAsync({
useFactory: (config: ConfigService) => ({ bucket: config.get("BUCKET") }),
inject: [ConfigService],
});
The forRootAsync variant lets configuration depend on other providers (like ConfigService) — essential when options come from validated configuration.
Dynamic modules and the forRoot/forFeature pattern are an important NestJS concept for building configurable, reusable modules — and understanding them is valuable both for using the ecosystem and for building shared modules.
Nearly every major NestJS module (ConfigModule, TypeOrmModule, JwtModule, BullModule, CacheModule) is a dynamic module configured via .forRoot()/.register()/.forFeature(), so recognizing what these calls are (passing configuration to a module at import time, rather than a static import) demystifies how the whole ecosystem is wired.
The forRoot vs forFeature convention (forRoot for one-time global setup like a database connection or secret; forFeature for per-feature registration like registering entities in each module) is a pattern you encounter constantly.
For senior developers, knowing how to build your own dynamic modules (returning a DynamicModule with providers configured from passed options, often via injection tokens, with async variants for config-dependent setup) is what lets you create reusable, configurable modules — shared infrastructure (storage, external API clients, custom config) that other parts of an app or other projects import with their own settings.
This is a more advanced topic, but it's fundamental to understanding NestJS's modular architecture deeply and to building professional, reusable module libraries, making it an important capability for architecting large, well-structured NestJS systems.