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.