Dynamic modules in NestJS

This chapter follows Configuration in NestJS.

The modules in Modules in NestJS are static: their providers are fixed in the @Module() decorator, and every importer gets the same thing. A reusable module, such as a database connection, a mail client, or ConfigModule itself, needs input from the app that uses it: a URI, an API key, a list of entities. A dynamic module is a static method on the module class that takes that input and returns module metadata built from it.

What a dynamic module returns

The method returns a DynamicModule: the same keys as @Module(), plus a module key naming the class. Options usually travel as a provider under a token of their own, so the module’s services can inject them:

1
import { DynamicModule, Module } from '@nestjs/common';
2
import { MailService } from './mail.service';
3

4
export const MAIL_OPTIONS = Symbol('MAIL_OPTIONS');
5

6
export interface MailOptions {
7
  apiKey: string;
8
  from: string;
9
}
10

11
@Module({})
12
export class MailModule {
13
  static forRoot(options: MailOptions): DynamicModule {
14
    return {
15
      module: MailModule,
16
      providers: [{ provide: MAIL_OPTIONS, useValue: options }, MailService],
17
      exports: [MailService],
18
    };
19
  }
20
}

1
@Injectable()
2
export class MailService {
3
  constructor(@Inject(MAIL_OPTIONS) private readonly options: MailOptions) {}
4
}

The metadata returned by forRoot() extends whatever the @Module() decorator declares. Adding global: true to the returned object makes the module global, which is how ConfigModule.forRoot({ isGlobal: true }) works.

forRoot, forFeature, and register

The method names are a convention that tells the reader how a module is meant to be used:

MongooseModule.forRoot() opens the connection once. MongooseModule.forFeature([{ name: Cat.name, schema: CatSchema }]) in CatsModule registers the Cat model on that connection and makes it injectable in that module only. The Mongoose chapter uses both.

Async configuration

Options passed to forRoot() must exist when the decorator is evaluated, which is before Nest has created a single provider. When the options come from ConfigService, they are not available yet. forRootAsync() moves the work into the injector by accepting a factory instead of a value:

1
@Module({
2
  imports: [
3
    ConfigModule.forRoot({ isGlobal: true }),
4
    MailModule.forRootAsync({
5
      inject: [ConfigService],
6
      useFactory: (config: ConfigService) => ({
7
        apiKey: config.getOrThrow('MAIL_API_KEY'),
8
        from: config.get('MAIL_FROM', 'noreply@example.com'),
9
      }),
10
    }),
11
  ],
12
})
13
export class AppModule {}

Inside the module, the factory simply becomes the options provider: { provide: MAIL_OPTIONS, useFactory: options.useFactory, inject: options.inject }. The factory may be async, for example to fetch a secret from a vault, and Nest waits for it before creating anything that depends on the options. An imports key lists modules the factory’s dependencies come from, when they are not global. Most library modules accept useClass and useExisting here as well.

Generating the boilerplate

Writing forRoot, forRootAsync, the options token, and their types by hand repeats across every reusable module. ConfigurableModuleBuilder generates them:

1
import { ConfigurableModuleBuilder } from '@nestjs/common';
2
import type { MailOptions } from './mail.options';
3

4
export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } =
5
  new ConfigurableModuleBuilder<MailOptions>().setClassMethodName('forRoot').build();

1
@Module({
2
  providers: [MailService],
3
  exports: [MailService],
4
})
5
export class MailModule extends ConfigurableModuleClass {}

MailModule now has forRoot() and forRootAsync() with the right types, and MailService injects its options with @Inject(MODULE_OPTIONS_TOKEN). setExtras() adds options that shape the module rather than the service, such as an isGlobal flag.

When to write one

Most feature modules in an application stay static. A dynamic module earns its place when the same module is used with different settings, or when it wraps a client library that needs configuration before it can be created: a mail provider, a payment SDK, a message broker. If a module is only ever imported once and reads its settings from ConfigService directly, a static module that injects ConfigService is simpler and just as testable.

Next: Application lifecycle hooks in NestJS.