Dynamic modules and async configuration

Static set vs runtime descriptor

A static @Module({ providers, exports }) has a fixed provider set, decided at class-definition time. It can’t take configuration — imports: [CacheModule] gives you whatever CacheModule decided for itself.

A dynamic module is a class with a static method that returns a DynamicModule descriptor at runtime: { module, providers, imports?, exports?, global? }. The importer calls that method and passes config, and Nest splices the returned providers into the graph. This is exactly how ConfigModule.forRoot({ ... }), JwtModule.register({ ... }), and TypeOrmModule.forFeature([ ... ]) work — each call is a method invocation that builds a tailored module on the spot.

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

export const STORAGE_OPTIONS = 'STORAGE_OPTIONS';
export interface StorageOptions { bucket: string; region: string; }

@Module({})
export class StorageModule {
  // hand-rolled dynamic module: the importer passes config, we turn it into a provider
  static forRoot(options: StorageOptions): DynamicModule {
    return {
      module: StorageModule,
      providers: [{ provide: STORAGE_OPTIONS, useValue: options }],
      exports: [STORAGE_OPTIONS], // so consumers can inject the options token
      global: true,               // exports visible app-wide without re-importing
    };
  }
}

StorageModule.forRoot({ bucket: 'uploads', region: 'eu-central-1' }) returns a fully-formed module whose single provider is the options object, exported under a token that downstream services inject. The @Module({}) shell is empty on purpose — the method is the real constructor.

The naming convention: forRoot, forFeature, register

The three method names are a convention, not enforced by Nest — but every Nest developer reads them as a contract, so breaking it is a footgun.

• forRoot() — configure once, at the app root. Typically returns the shared infrastructure (a connection, a config store) and is often global. Calling it more than once is the bug in the hook.
• forFeature() — register a slice, repeatedly, per feature module. TypeOrmModule.forFeature([User]) in one module, forFeature([Order]) in another — each call scopes repositories into that module without re-creating the connection forRoot already made.
• register() — per-import configuration with no root/global semantics. Each HttpModule.register({ baseURL }) is independent; two imports mean two separately-configured instances, and that’s intended.

// forRoot ONCE, at the root — stands up the shared connection (global)
imports: [DatabaseModule.forRoot({ url: process.env.DB_URL, poolSize: 10 })]

// forFeature PER module — scopes entities/repos, reuses the forRoot connection
imports: [DatabaseModule.forFeature([User])]   // in UsersModule
imports: [DatabaseModule.forFeature([Order])]  // in OrdersModule

// register PER import — each gets its own independent config, no sharing implied
imports: [HttpModule.register({ baseURL: 'https://api.billing.internal' })]

Together the three names encode the sharing intent: forRoot means “one shared pool for the whole app”, forFeature means “slice of that pool, per module”, and register means “independent instance, no sharing”. When you see a colleague call forRoot in a feature module, that’s the 2am incident waiting to happen — the name itself is the contract.

Async config: forRootAsync and the factory provider

The hand-rolled forRoot above takes a literal options object. But the real config — a DB URL, a JWT secret — lives in env and is read by ConfigService. You can’t pass a literal at import time; you need the value resolved from another provider. That’s forRootAsync:

import { JwtModule } from '@nestjs/jwt';
import { ConfigModule, ConfigService } from '@nestjs/config';

JwtModule.registerAsync({
  imports: [ConfigModule],            // make ConfigService resolvable IN this context
  inject: [ConfigService],            // the factory's dependencies, in order
  useFactory: (cfg: ConfigService) => ({
    secret: cfg.getOrThrow('JWT_SECRET'),
    signOptions: { expiresIn: cfg.get('JWT_TTL') ?? '15m' },
  }),
});

Three pieces work together. useFactory is itself a provider — a function Nest calls to produce the options. inject lists that function’s dependencies, positionally, so Nest knows to resolve ConfigService and pass it as the first argument. imports makes those dependencies resolvable inside the dynamic module’s own injection context — a dynamic module has its own scope, so unless ConfigModule is global, the factory can’t see ConfigService without importing it here.

Forget imports: [ConfigModule] (and ConfigModule isn’t global), and you get a boot-time crash, not a runtime one: Nest can't resolve dependencies of the <factory> (?). Please make sure that the argument ConfigService at index [0] is available in the <module> context. The (?) is the unresolved ConfigService — the factory declared it via inject but nothing in scope provides it.

ConfigurableModuleBuilder: stop hand-rolling

Writing forRoot and forRootAsync by hand — the literal path, the factory path, the useExisting/useClass async variants, the options token — is ~40 lines of boilerplate per module, repeated identically across every configurable module you own. ConfigurableModuleBuilder generates all of it:

import { ConfigurableModuleBuilder } from '@nestjs/common';
import { StorageOptions } from './storage-options.interface';

// generates the class + token + sync AND async entry points for you
export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
  new ConfigurableModuleBuilder<StorageOptions>().build();

import { Module } from '@nestjs/common';
import { ConfigurableModuleClass } from './storage.module-definition';

@Module({ providers: [StorageService], exports: [StorageService] })
export class StorageModule extends ConfigurableModuleClass {}
// now StorageModule.register({...}) AND StorageModule.registerAsync({ useFactory, inject, imports })
// both exist, and StorageService can inject MODULE_OPTIONS_TOKEN

The builder hands back ConfigurableModuleClass (extend it) and MODULE_OPTIONS_TOKEN (inject it to read the options). You get both register and registerAsync for free, with the imports/inject/useFactory async plumbing already wired. Want forRoot naming instead of register? .setClassMethodName('forRoot'). Want it global? .setExtras({ isGlobal: true }, ...). The ~40 lines per module collapse to two.