Dynamic modules in NestJS - Deep Dive

Overview - Dynamic modules

What is it?

Dynamic modules in NestJS are special modules that can be configured and created at runtime. Unlike static modules, which are fixed when the app starts, dynamic modules allow you to pass options and customize providers before the app fully loads. This helps build flexible and reusable parts of your application that adapt to different needs.

Why it matters

Without dynamic modules, every module would be rigid and fixed, forcing you to duplicate code or write many similar modules for different cases. Dynamic modules solve this by letting you create configurable modules once and reuse them with different settings. This saves time, reduces errors, and makes your app easier to maintain and scale.

Where it fits

Before learning dynamic modules, you should understand basic NestJS modules, providers, and dependency injection. After mastering dynamic modules, you can explore advanced patterns like custom providers, global modules, and module refactoring for large apps.

Mental Model

Core Idea

Dynamic modules are like customizable blueprints that build different versions of a module based on the options you give them at startup.

Think of it like...

Imagine ordering a pizza where you choose the size, toppings, and crust type. The pizza shop uses one recipe but makes each pizza unique based on your choices. Dynamic modules work the same way—they use one module structure but customize it with your options.

┌───────────────────────────────┐
│        Dynamic Module          │
│  ┌───────────────┐            │
│  │  Options in   │            │
│  │  for Config   │            │
│  └──────┬────────┘            │
│         │                    │
│  ┌──────▼────────┐           │
│  │  Providers    │           │
│  │  & Services   │           │
│  └──────┬────────┘           │
│         │                    │
│  ┌──────▼────────┐           │
│  │  Module with  │           │
│  │  Custom Setup │           │
│  └───────────────┘           │
└───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding NestJS Modules

Concept: Learn what a module is in NestJS and how it organizes code.

In NestJS, a module is a class annotated with @Module decorator. It groups related controllers, providers, and other modules. Modules help organize your app into logical units. For example, a UserModule might handle user logic, while an AuthModule handles authentication.

Result

You can create a simple module that bundles providers and controllers together.

Understanding modules is essential because dynamic modules build on this concept by adding flexibility to how modules are created.

2

Foundation

Basic Static Module Setup

Concept: Learn how to create a static module with fixed providers.

A static module defines providers and exports them without any runtime configuration. For example: @Module({ providers: [CatsService], exports: [CatsService], }) export class CatsModule {} This module always provides CatsService the same way.

Result

The module provides the same services every time the app runs.

Static modules are simple but inflexible; they cannot change behavior based on input, which limits reuse.

3

Intermediate

Creating a Dynamic Module Factory

🤔Before reading on: do you think a dynamic module returns a class or an object? Commit to your answer.

Concept: Dynamic modules are created by a static method that returns a module definition object with configuration.

To create a dynamic module, define a static method (usually called forRoot or forRootAsync) that accepts options and returns a ModuleMetadata object. Example: @Module({}) export class ConfigModule { static forRoot(options: { envFilePath: string }): DynamicModule { return { module: ConfigModule, providers: [ { provide: 'CONFIG_OPTIONS', useValue: options }, ConfigService, ], exports: [ConfigService], }; } } This lets you pass options when importing the module.

Result

You get a module customized with the options you passed, changing its providers accordingly.

Knowing that dynamic modules return a module object, not just a class, is key to understanding how NestJS builds flexible modules.

4

Intermediate

Using Dynamic Modules with Dependency Injection

🤔Before reading on: do you think providers in dynamic modules can access the passed options directly? Commit to your answer.

Concept: Providers inside dynamic modules can inject the options passed via tokens to customize their behavior.

In the previous example, ConfigService can inject 'CONFIG_OPTIONS' to access the options: @Injectable() export class ConfigService { constructor(@Inject('CONFIG_OPTIONS') private options) {} getEnvFilePath() { return this.options.envFilePath; } } This allows services to adapt based on module configuration.

Result

Providers behave differently depending on the options passed to the dynamic module.

Understanding how to inject configuration tokens inside dynamic modules unlocks powerful customization patterns.

5

Intermediate

Global Dynamic Modules for App-wide Config

Concept: Dynamic modules can be made global so their providers are available everywhere without importing repeatedly.

Add global: true to the returned module object: return { module: ConfigModule, global: true, providers: [...], exports: [...], }; This makes the module's providers accessible in any module without explicit imports.

Result

You can use the configured services anywhere in the app without importing the module multiple times.

Global dynamic modules simplify app-wide configuration and reduce boilerplate imports.

6

Advanced

Async Dynamic Modules for External Config

🤔Before reading on: do you think async dynamic modules block app startup? Commit to your answer.

Concept: Dynamic modules can load configuration asynchronously, for example from a database or remote service, before app startup completes.

Use forRootAsync with imports and useFactory: @Module({}) export class ConfigModule { static forRootAsync(options: { imports?: any[]; useFactory: (...args: any[]) => Promise | any; inject?: any[]; }): DynamicModule { return { module: ConfigModule, imports: options.imports || [], providers: [ { provide: 'CONFIG_OPTIONS', useFactory: options.useFactory, inject: options.inject || [], }, ConfigService, ], exports: [ConfigService], }; } } This pattern supports async setup and blocks app startup until config is ready.

Result

The app waits for async config to load before finishing startup, ensuring providers have correct data.

Async dynamic modules enable flexible, real-world scenarios like loading secrets or remote configs safely before app runs.

7

Expert

Dynamic Module Internals and Caching

🤔Before reading on: do you think NestJS creates a new instance of a dynamic module each time it is imported? Commit to your answer.

Concept: NestJS caches dynamic modules by their module reference, so importing the same dynamic module with identical options reuses the instance, but different options create separate instances.

When you import a dynamic module multiple times with different options, NestJS treats each as a unique module instance. Internally, it tracks modules by their metadata and options to avoid conflicts. This caching mechanism ensures providers are singleton per module instance but allows multiple configured versions in the app.

Result

You can safely import dynamic modules multiple times with different configs without provider clashes.

Understanding this caching prevents bugs where multiple module instances unexpectedly share state or cause conflicts.

Under the Hood

Dynamic modules work by returning a ModuleMetadata object from a static method. NestJS uses this metadata to build the module graph at runtime. Providers configured with useValue or useFactory receive the passed options via dependency injection tokens. NestJS caches module instances keyed by their configuration to manage multiple versions. This runtime flexibility is possible because NestJS compiles and resolves modules dynamically before app bootstrap.

Why designed this way?

NestJS was designed to support scalable, modular apps. Static modules were too rigid for real-world needs where configuration varies by environment or use case. Dynamic modules provide a clean, declarative way to customize modules without losing the benefits of NestJS's dependency injection and modular architecture. Alternatives like manual provider registration were error-prone and verbose.

┌───────────────────────────────┐
│  App Bootstrap                │
│  ┌─────────────────────────┐ │
│  │ Dynamic Module Factory   │ │
│  │ (forRoot / forRootAsync) │ │
│  └─────────────┬───────────┘ │
│                │             │
│  ┌─────────────▼───────────┐ │
│  │ ModuleMetadata Object    │ │
│  │ - module class           │ │
│  │ - providers              │ │
│  │ - exports                │ │
│  │ - global flag            │ │
│  └─────────────┬───────────┘ │
│                │             │
│  ┌─────────────▼───────────┐ │
│  │ NestJS Module Loader     │ │
│  │ - Registers providers    │ │
│  │ - Injects options tokens │ │
│  │ - Caches module instances│ │
│  └─────────────┬───────────┘ │
│                │             │
│  ┌─────────────▼───────────┐ │
│  │ Application Context      │ │
│  │ - Providers available    │ │
│  │ - Modules wired up       │ │
│  └─────────────────────────┘ │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does importing a dynamic module twice with the same options create two separate instances? Commit yes or no.

Common Belief: Importing a dynamic module multiple times always creates multiple instances of its providers.

Reality: NestJS caches dynamic modules by their configuration, so importing with the same options reuses the same module instance and providers.

Why it matters: Without this caching, apps would waste memory and risk inconsistent state by duplicating providers unnecessarily.

Quick: Can dynamic modules only be used for configuration? Commit yes or no.

Common Belief: Dynamic modules are only useful for passing simple configuration options like strings or numbers.

Reality: Dynamic modules can accept complex options, async factories, and even import other modules dynamically, enabling powerful patterns beyond simple config.

Why it matters: Limiting dynamic modules to simple config misses their full potential for flexible app architecture.

Quick: Do dynamic modules replace static modules completely? Commit yes or no.

Common Belief: Dynamic modules are always better and should replace static modules everywhere.

Reality: Static modules are simpler and sufficient when no configuration is needed; dynamic modules add complexity and should be used only when flexibility is required.

Why it matters: Overusing dynamic modules can make code harder to read and maintain without real benefit.

Quick: Does the global flag in dynamic modules make providers available everywhere without imports? Commit yes or no.

Common Belief: Setting global: true on a dynamic module means you never need to import it anywhere else.

Reality: Global modules make providers available app-wide, but you still need to import the module once in the root or a shared module.

Why it matters: Misunderstanding this can cause runtime errors due to missing module imports.

Expert Zone

1

Dynamic modules can import other dynamic modules, creating complex dependency graphs that require careful option management to avoid circular dependencies.

2

Using useFactory with async providers in dynamic modules allows integration with external services like databases or config servers, but requires understanding NestJS lifecycle hooks to avoid startup delays.

3

The module caching mechanism keys modules by their class and options object identity, so passing new option objects with identical content creates new module instances, which can cause subtle bugs.

When NOT to use

Avoid dynamic modules when your module does not require runtime configuration or when the configuration is static and known at compile time. In such cases, use static modules for simplicity and better performance. Also, if your configuration is simple, consider environment variables or global providers instead of dynamic modules.

Production Patterns

In production, dynamic modules are commonly used for database modules (e.g., TypeORMModule.forRoot), configuration modules that load environment variables, and third-party integrations that require setup options. They enable multi-tenant apps by creating module instances per tenant with different configs. Experts also combine dynamic modules with global modules to provide app-wide services with flexible setup.

Connections

Factory Pattern (Software Design)

Dynamic modules implement a factory pattern by producing module instances based on input options.

Understanding dynamic modules as factories helps grasp how NestJS creates customized modules on demand, similar to how factories produce objects with different configurations.

Dependency Injection

Dynamic modules leverage dependency injection to pass configuration options to providers.

Knowing how dependency injection works clarifies how dynamic modules supply runtime data to services cleanly and flexibly.

Cooking Recipes (Real-world Process)

Dynamic modules are like recipes that can be adjusted with different ingredients to produce varied dishes.

This connection shows how modular, configurable processes in cooking mirror software module customization, emphasizing adaptability and reuse.

Common Pitfalls

#1 Passing a new options object each time causes multiple module instances.

Wrong approach:

imports: [ConfigModule.forRoot({ envFilePath: '.env' })],
imports: [ConfigModule.forRoot({ envFilePath: '.env' })],

Correct approach:

const configOptions = { envFilePath: '.env' };
imports: [ConfigModule.forRoot(configOptions), ConfigModule.forRoot(configOptions)],

Root cause:

Each object literal is a new reference, so NestJS treats them as different configs, creating multiple module instances.

#2 Forgetting to export providers from dynamic modules makes them unavailable outside.

Wrong approach:

return {
module: ConfigModule,
providers: [ConfigService],
// missing exports
};

Correct approach:

return {
module: ConfigModule,
providers: [ConfigService],
exports: [ConfigService],
};

Root cause:

Not exporting providers means other modules cannot inject them, breaking dependency injection.

#3 Using global: true without importing the module once causes runtime errors.

Wrong approach:

// No import of ConfigModule anywhere
// Trying to inject ConfigService fails

Correct approach:

imports: [ConfigModule.forRoot({ envFilePath: '.env' })], // import once in root module

Root cause:

Global modules still require one import to register providers; skipping this causes missing provider errors.

Key Takeaways

Dynamic modules let you create flexible, configurable NestJS modules that adapt at runtime.

They work by returning a module definition object with providers customized by passed options.

Dynamic modules support async configuration and global scope for app-wide services.

NestJS caches dynamic modules by their options to avoid duplicate instances and conflicts.

Using dynamic modules wisely improves code reuse, maintainability, and scalability in real-world apps.

Practice

1. What is the main purpose of a dynamic module in NestJS?

easy

A. To automatically generate database schemas

B. To create modules without any providers or exports

C. To replace the need for controllers in an application

D. To allow configuration of modules with custom options at runtime

Solution

1. Step 1: Understand dynamic module concept

   Dynamic modules let you pass custom options to configure the module when importing it.

2. Step 2: Identify the main purpose

   This flexibility helps reuse modules with different settings instead of hardcoding them.

3. Final Answer:

   To allow configuration of modules with custom options at runtime -> Option D

4. Quick Check:

   Dynamic modules = configurable modules [OK]

Hint: Dynamic modules customize modules with options [OK]

Common Mistakes:

• Thinking dynamic modules remove controllers
• Believing dynamic modules auto-generate schemas
• Assuming dynamic modules have no providers

2. Which of the following is the correct way to define a dynamic module method in NestJS?

easy

A. constructor(options: ModuleOptions): void { ... }

B. static forRoot(options: ModuleOptions): DynamicModule { ... }

C. export function createModule(options: ModuleOptions) { ... }

D. async initialize(options: ModuleOptions): Promise<void> { ... }

Solution

1. Step 1: Recall dynamic module pattern

   Dynamic modules use a static method, commonly named forRoot, returning a DynamicModule object.

2. Step 2: Match method signature

   Only a static method can be called without creating an instance, fitting the dynamic module pattern.

3. Final Answer:

   static forRoot(options: ModuleOptions): DynamicModule { ... } -> Option B

4. Quick Check:

   Dynamic module method = static forRoot [OK]

Hint: Dynamic modules use static forRoot method [OK]

Common Mistakes:

• Using constructor instead of static method
• Defining dynamic module as a normal function
• Making dynamic module method async without returning DynamicModule

3. Given this dynamic module code, what will be the value of the exported provider's token?

export class LoggerModule {
  static forRoot(prefix: string): DynamicModule {
    return {
      module: LoggerModule,
      providers: [
        { provide: 'LOGGER_PREFIX', useValue: prefix },
      ],
      exports: ['LOGGER_PREFIX'],
    };
  }
}

medium

A. 'prefix'

B. 'LoggerModule'

C. 'LOGGER_PREFIX'

D. 'useValue'

Solution

1. Step 1: Identify provider token

   The provider uses the key 'provide' with value 'LOGGER_PREFIX' which is the token for injection.

2. Step 2: Confirm exported token

   The exports array includes 'LOGGER_PREFIX', so this token is available outside the module.

3. Final Answer:

   'LOGGER_PREFIX' -> Option C

4. Quick Check:

   Provider token = 'LOGGER_PREFIX' [OK]

Hint: Provider token is the 'provide' string value [OK]

Common Mistakes:

• Confusing module name with provider token
• Using variable name 'prefix' as token
• Thinking useValue is the token

4. Identify the error in this dynamic module definition:

export class CacheModule {
  static forRoot(options: { ttl: number }): DynamicModule {
    return {
      module: CacheModule,
      providers: [
        { provide: 'CACHE_TTL', useFactory: (options) => options.ttl },
      ],
      exports: ['CACHE_TTL'],
    };
  }
}

medium

A. The useFactory function cannot access options parameter directly

B. The module property should be a string, not a class

C. Exports array must include providers, not strings

D. Static methods cannot return DynamicModule

Solution

1. Step 1: Analyze useFactory context

   The useFactory function runs later and cannot directly access the outer options variable without injection.

2. Step 2: Identify correct pattern

   To use options inside useFactory, it must be passed via inject or closure properly; direct access causes runtime error.

3. Final Answer:

   The useFactory function cannot access options parameter directly -> Option A

4. Quick Check:

   useFactory needs inject or closure for options [OK]

Hint: useFactory can't directly use outer variables [OK]

Common Mistakes:

• Thinking module property must be string
• Believing exports must list provider objects
• Assuming static methods can't return DynamicModule

5. You want to create a dynamic module that accepts a configuration object and provides two services using that config. Which approach correctly implements this pattern?

hard

A. Use a static forRoot method returning a DynamicModule with providers using useValue for config and export both services

B. Create a constructor in the module class that sets config and exports services directly

C. Define services inside the module without any configuration and import them normally

D. Use a global module without any providers and configure services externally

Solution

1. Step 1: Understand dynamic module pattern for config

   Dynamic modules use a static method (like forRoot) to accept config and return a DynamicModule object with providers.

2. Step 2: Provide config and services properly

   Use useValue or useFactory to inject config into providers, and export services to make them available outside.

3. Final Answer:

   Use a static forRoot method returning a DynamicModule with providers using useValue for config and export both services -> Option A

4. Quick Check:

   Dynamic module with static forRoot and providers = Use a static forRoot method returning a DynamicModule with providers using useValue for config and export both services [OK]

Hint: Use static forRoot with providers and exports [OK]

Common Mistakes:

• Trying to configure modules via constructor
• Not exporting services after providing them
• Using global module without providers for config