Dynamic modules and ConfigurableModuleBuilder

TiffinTrail sends lunch reminders by SMS, and so does Kharcha, a second app built on the same code: one SmsModule, two sender ids, TFNTRL and KHRCHA, and two keys. A module described only by its @Module() decorator has nowhere to take them.

Dynamic modulesdynamic module: A module configured by a method call, such as SmsModule.forRoot(options): the method returns the module class with extra metadata, often the caller's settings as a provider, which Nest adds to the class's @Module() lists. do: a static method takes the caller’s settings and returns the module’s metadata with them. This lesson writes one by hand, names the conventions forRoot(), register() and forFeature(), generates the methods with ConfigurableModuleBuilder, and reads the settings from ConfigService and checks them while the app starts.

A dynamic module is a module made by a method call

SmsModule lists SmsService in its @Module() decorator, and SmsService asks for its settings under a symbol token, SMS_OPTIONS, as the custom providers lesson did for its gateway. The decorator cannot hold the settings, because they differ for every app. So the module gets a static method, forRoot(options), that returns a DynamicModule: an object with the module class and the providers to add, here the options as a useValue provider.

import { type DynamicModule, Inject, Injectable, Module } from '@nestjs/common';

export interface SmsOptions {
  /** The sender name a phone shows, such as TFNTRL. */
  senderId: string;
  /** The gateway's key. The examples send through a local fake gateway, so any text works. */
  apiKey: string;
}

export const SMS_OPTIONS = Symbol('SMS_OPTIONS');
export const SMS_TEMPLATES = Symbol('SMS_TEMPLATES');

@Injectable()
export class SmsService {
  static built = 0;

  constructor(@Inject(SMS_OPTIONS) private readonly options: SmsOptions) {
    SmsService.built += 1;
  }

  /** Sends nothing: returns the line the local fake gateway would deliver. */
  send(to: string, text: string): string {
    return `${this.options.senderId} -> ${to}: ${text}`;
  }
}

/** One feature's message templates, sent through the app's SmsService. */
@Injectable()
export class SmsTemplates {
  constructor(
    private readonly sms: SmsService,
    @Inject(SMS_TEMPLATES) private readonly templates: Record<string, string>,
  ) {}

  send(to: string, name: string): string {
    return this.sms.send(to, this.templates[name] ?? `no template called ${name}`);
  }
}

@Module({})
export class SmsFeatureModule {}

@Module({
  providers: [SmsService],
  exports: [SmsService],
})
export class SmsModule {
  /** Configures the gateway once, in the root module; global, so that every feature can inject SmsService. */
  static forRoot(options: SmsOptions): DynamicModule {
    return {
      module: SmsModule,
      global: true,
      providers: [{ provide: SMS_OPTIONS, useValue: options }],
    };
  }

  /** Gives the calling feature its own templates, sent through the SmsService that forRoot() configured. */
  static forFeature(templates: Record<string, string>): DynamicModule {
    return {
      module: SmsFeatureModule,
      providers: [{ provide: SMS_TEMPLATES, useValue: templates }, SmsTemplates],
      exports: [SmsTemplates],
    };
  }
}

Nest reads the returned object as more metadata for SmsModule. The Nest documentation says it extends, rather than overrides, what @Module() lists. Step through what happens in each app:

import { session } from '../session.mjs';

// One SmsModule, imported as a plain class and then configured by two apps with forRoot().
session(`
npx tsc -p tsconfig.json
node dist/forroot.js
`);

$ npx tsc -p tsconfig.json
$ node dist/forroot.js
SmsModule.forRoot() returned:
   module: SmsModule, global: true
   providers: { provide: Symbol(SMS_OPTIONS), useValue: { senderId: 'TFNTRL', apiKey: '…' } }
AppWithThePlainModule: Nest can't resolve dependencies of the SmsService (?). Please make sure that the argument Symbol(SMS_OPTIONS) at index [0] is available in the SmsModule module.
TiffinTrailApp: TFNTRL -> cus-41: Your lunch leaves the kitchen at 12:10
KharchaApp: KHRCHA -> cus-41: Your lunch leaves the kitchen at 12:10

The first lines show the object forRoot() returned: SmsModule, global: true and one provider holding the settings. The plain import failed, because SmsService was there and its options were not. TiffinTrailApp and KharchaApp each got an SmsService with its own sender, from one module’s code. Dynamic modules are how Nest’s own packages take their settings, from database connections to GraphQL servers.

This forRoot() is meant to be called once, in the root module, which is why it returns global: true: every feature can then inject SmsService without an import. That is the case in which the modules lesson accepts a global module, infrastructure configured once for the whole app. The forFeature() method at the bottom of the file belongs to the next section.

forRoot, register and forFeature tell callers how often to configure

The method’s name is a convention, not a rule: the documentation says there is no hard rule, and Nest runs forRoot() and register() alike. Nest’s own packages give the names fixed meanings, and callers rely on them:

In SmsModule, forFeature() gives each feature its own message templates, which send through the one SmsService that forRoot() configured. Each async variant takes imports, inject and useFactory instead of the options, so the settings can come from ConfigService or a secrets store while the app starts, not when the file is loaded. Instead of useFactory, a caller may pass useClass, a class with a method that returns the options (create() in the modules ConfigurableModuleBuilder generates), or useExisting, a provider the app already has with that method.

Writing forRoot() and forRootAsync() by hand for every reusable module repeats the same code, and the async half is the easy one to get wrong. ConfigurableModuleBuilderConfigurableModuleBuilder: A class of @nestjs/common that generates a dynamic module's methods, register() and registerAsync() unless renamed, from an options interface, together with the token its options are provided under., from @nestjs/common, generates both from an options interface: its build() returns a class to extend and MODULE_OPTIONS_TOKENMODULE_OPTIONS_TOKEN: The injection token under which a module built with ConfigurableModuleBuilder provides the options its caller passed; the module's classes inject the options with @Inject(MODULE_OPTIONS_TOKEN)., the token the options are provided under. ConfigurableModuleBuilder names the methods register() and registerAsync() unless setClassMethodName() renames them.

ConfigurableModuleBuilder, generated and run, with forRootAsync() three ways Pro: opens with a Pro, Premium or Ultimate pass

Options that stop start-up with a clear message, not on the first SMS Pro: opens with a Pro, Premium or Ultimate pass

How many instances forRoot() gives you, measured in six apps Pro: opens with a Pro, Premium or Ultimate pass

Practise: dynamic modules

The questions check the two ideas of the first sections: what a forRoot() call adds to a module, and which convention fits a module’s callers.

Interview questions

Key takeaways

• A dynamic module is a module class plus the metadata that a static method returns with the caller’s settings, and Nest adds that metadata to the lists of the class’s @Module().
• Importing the class alone gives only its @Module() part, so a provider that needs the options cannot be built.
• forRoot() configures a module once for the app, register() once for each importer, and forFeature() adds a feature’s own pieces; the async variants build the options with a factory while the app starts.
• ConfigurableModuleBuilder generates those methods and the options token from an options interface.