nestjs-smart-modules

Transform NestJS modules into composable, type-safe building blocks. Configure once, compose everywhere.

Key Features

• One-Line Integration - Works with existing NestJS code
• 100% Type-Safe - Full TypeScript support with autocompletion
• True Composition - Modules automatically include dependencies
• Zero Boilerplate - Service class becomes the module
• Flexible Architecture - Single or multiple instances with namespacing
• Tree-Shakeable - Bundle only what you use

Quick Start

Transform any service into a smart module in seconds:

import { Injectable, Module } from '@nestjs/common'
import { smartModule } from 'nestjs-smart-modules'

// 1. Define your configuration
export class DatabaseConfig {
  url: string
  poolSize?: number = 10
}

// 2. Create your service with embedded module definition
@Injectable()
export class DatabaseService {
  static smartModule = smartModule({
    smartConfigs: [DatabaseConfig],
    providers: [DatabaseService],
    exports: [DatabaseService],
  })

  constructor(private config: DatabaseConfig) {}

  query(sql: string) {
    return `Executing: ${sql} on ${this.config.url}`
  }
}

// 3. Create a feature service that depends on DatabaseService
@Injectable()
export class FeatureService {
  static smartModule = smartModule({
    smartImports: [DatabaseService.smartModule],
    providers: [FeatureService],
    exports: [FeatureService],
  })

  constructor(private db: DatabaseService) {}

  getUsers() {
    return this.db.query('SELECT * FROM users')
  }
}

// 4. Use it anywhere with full type safety - configuration flows down automatically
@Module({
  imports: [
    FeatureService.smartModule({
      url: 'postgres://localhost:5432/mydb',
    }),
  ],
})
export class AppModule {}
Copy

✅ Test easily - Provide only what each module needs at any level

How It Works

Smart modules automatically build your dependency tree and merge configuration requirements:

// Your dependency tree
AppModule
  └── FeatureService.smartModule({ url: "..." }) // Pass config at the top level
       └── DatabaseService.smartModule           // Gets config automatically!
            └── DatabaseConfig                   // Configured once at the root
Copy

This works in three steps:

1. Dependency Discovery - The library walks your entire dependency tree
2. Configuration Merging - It collects all config requirements into one object
3. Smart Distribution - It delivers the right config to each module automatically

Table of Contents

• Installation
• Compatibility
• Basic Usage
  • Creating a Module with a Configuration Class
• Configuration
  • Namespacing with Labels and Prefixes
  • Labels: Grouping Under Nested Objects
  • Prefixes: Flattened Property Naming
• Module Composition
  • Importing Other Smart Modules
  • Advanced: Namespacing Composed Modules
  • Instance Semantics
• Advanced Usage
  • Using Injection Tokens
  • Asynchronous Configuration
  • Module Definition Factory
• Recipes
  • Multiple Instances of a Module
  • Global Configuration Module
• Why Not ConfigurableModuleBuilder?
• API Reference

Installation

npm install nestjs-smart-modules
Copy

Compatibility

CI runs the full compatibility grid — every supported NestJS major against every Node line it supports: Nest 8/9/10 on Node 18.16 (the declared floor), 20, 22, 24 and 26, and Nest 11 on Node 20+ (its own engines requirement). NestJS 12 (@next) is tracked by a warning-only job until its RC. The package ships dual builds: CommonJS for require() and ESM for import. Development happens on the Node version pinned in .nvmrc. Built with TypeScript 5.8; public factory type inference is verified in CI down to TypeScript 5.0.

Basic Usage

Creating a Module with a Configuration Class

This is the most common use case. You provide a configuration class via smartConfigs, and smartModule handles the configuration and dependency injection.

Config Class:

// auth.config.ts
export class AuthConfig {
  // A required property must be provided when configuring the module.
  jwtSecret: string

  // An optional property can be omitted. It will be `undefined` if not provided.
  audience?: string

  // A property with a default value.
  // For this to be truly optional at the configuration stage,
  // it MUST be marked with a `?`.
  expiresIn?: string = '60s'
}
Copy

Important: Always mark properties with default values as optional with a ? (e.g., myProp?: string = 'default'). Without the ?, TypeScript will require you to provide a value for that property when you configure the module, even though it has a default.

Smart Module and Service:

// auth.service.ts
import { Injectable } from '@nestjs/common'
import { smartModule } from 'nestjs-smart-modules'
import { AuthConfig } from './auth.config'

@Injectable()
export class AuthService {
  static smartModule = smartModule({
    smartConfigs: [AuthConfig], // Use the `smartConfigs` property here
    providers: [AuthService],
    exports: [AuthService],
  })

  constructor(private readonly config: AuthConfig) {
    // You can access the fully instantiated config here
  }
}
Copy

Usage:

// app.module.ts
import { Module } from '@nestjs/common'
import { AuthService } from './auth.service'

@Module({
  imports: [
    AuthService.smartModule({
      jwtSecret: 'your-super-secret-key',
      // `audience` is omitted
      // `expiresIn` is omitted, so it will use the default '60s'
    }),
  ],
})
export class AppModule {}
Copy

Configuration

Namespacing with Labels and Prefixes

Both labels and prefixes solve the same problem: avoiding configuration property conflicts. When composing multiple modules or using multiple instances of the same module, you need ways to separate their configurations.

Important: When defining a label or prefix inline, always use as const. This tells TypeScript to treat it as a literal type, which is essential for correct type inference.

Note on smartImports: Applying a label or prefix to a smartImport only affects how configuration is passed down to it. It does not change the providers or injection tokens within the imported module itself.

Labels: Grouping Under Nested Objects

Labels create a nested object structure in your configuration. This is useful for logically grouping related settings or avoiding property name conflicts.

Example: Using Labels

// Two configs with a conflicting 'port' property.
export class DatabaseConfig {
  port: number
}
export class CacheConfig {
  port: number
}

export class AppService {
  static smartModule = smartModule({
    smartConfigs: [
      { smartConfig: DatabaseConfig, label: 'db' as const },
      { smartConfig: CacheConfig, label: 'cache' as const },
    ],
  })
}

@Module({
  imports: [
    AppService.smartModule({
      db: { port: 5432 },
      cache: { port: 6379 },
    }),
  ],
})
export class AppModule {}
Copy

You can also define a default label directly on the configuration class using a static property. It will be used automatically unless overridden.

Example: Static Labels

// Two configs with a conflicting 'port' property and static labels.
export class EmailConfig {
  static label = 'email' as const
  port: number
}
export class SmsConfig {
  static label = 'sms' as const
  port: number
}

export class NotificationsService {
  static smartModule = smartModule({
    // The static `label` on each class is used automatically.
    smartConfigs: [EmailConfig, SmsConfig],
  })
}

@Module({
  imports: [
    NotificationsService.smartModule({
      email: { port: 587 },
      sms: { port: 443 },
    }),
  ],
})
export class AppModule {}
Copy

Note: A static label on a config class will be overridden if you provide a label property inline where the class is used.

Prefixes: Flattened Property Naming

Prefixes add a prefix to each property name, creating a flat configuration structure. This is useful for avoiding property name conflicts while keeping all settings at the same level.

Example: Using Prefixes

// Two configs with a conflicting 'port' property.
export class DatabaseConfig {
  port: number
}
export class CacheConfig {
  port: number
}

export class AppService {
  static smartModule = smartModule({
    smartConfigs: [
      { smartConfig: DatabaseConfig, prefix: 'db_' as const },
      { smartConfig: CacheConfig, prefix: 'cache_' as const },
    ],
  })
}

@Module({
  imports: [
    AppService.smartModule({
      db_port: 5432,
      cache_port: 6379,
    }),
  ],
})
export class AppModule {}
Copy

A static prefix can also be defined directly on the configuration class.

Example: Static Prefixes

// Two configs with a conflicting 'port' property and static prefixes.
export class EmailConfig {
  static prefix = 'email_' as const
  port: number
}
export class SmsConfig {
  static prefix = 'sms_' as const
  port: number
}

export class NotificationsService {
  static smartModule = smartModule({
    // The static `prefix` on each class is used automatically.
    smartConfigs: [EmailConfig, SmsConfig],
  })
}

@Module({
  imports: [
    NotificationsService.smartModule({
      email_port: 587,
      sms_port: 443,
    }),
  ],
})
export class AppModule {}
Copy

Note: A static prefix on a config class will be overridden if you provide a prefix property inline where the class is used.

Module Composition

Module composition enables building applications as dependency trees. Each service defines its smartModule with dependencies, and the library merges all configuration requirements into a single root object.

// users.service.ts
export class UsersService {
  static smartModule = smartModule({
    // It IMPORTS another service's smartModule
    smartImports: [DatabaseService.smartModule],
    providers: [UsersService],
    exports: [UsersService],
  })
  // ...
}
Copy

// app.module.ts
@Module({
  imports: [
    // AppModule IMPORTS a feature module using .forRoot()
    UsersModule.forRoot({ ... }),
    GlobalConfigModule.forRoot({ ... }),
  ],
})
export class AppModule {}
Copy

Importing Other Smart Modules

Use smartImports to compose services. When one smart module imports another, the library merges configuration requirements. You only need to provide configuration for "leaf" nodes at the application's top level.

Example: A Multi-Level Dependency Tree

This example demonstrates a dependency tree:

graph TD
    App["AppModule"] --> Books["BooksService"]
    Books --> Users["UsersService"]
    Books --> DB1["DatabaseService"]
    Users --> DB2["DatabaseService"]

    Config["{ url: 'postgres://my-app-db' }"] --> App
    Config -.->|"shared config"| DB1
    Config -.->|"shared config"| DB2

    style App fill:#fff3e0
    style Books fill:#e8f5e8
    style Users fill:#e1f5fe
    style DB1 fill:#f3e5f5
    style DB2 fill:#f3e5f5
    style Config fill:#fce4ec
Copy

// 1. The deepest dependency, requiring a `url` for its configuration.
export class DatabaseConfig {
  url: string
}

@Injectable()
export class DatabaseService {
  static smartModule = smartModule({
    smartConfigs: [DatabaseConfig],
    providers: [DatabaseService],
    exports: [DatabaseService],
  })
  constructor(private readonly config: DatabaseConfig) {}
}

// 2. A service that depends on DatabaseService.
@Injectable()
export class UsersService {
  static smartModule = smartModule({
    smartImports: [DatabaseService.smartModule],
    providers: [UsersService],
    exports: [UsersService],
  })
  constructor(private readonly dbService: DatabaseService) {}
}

// 3. A top-level service that depends on both.
@Injectable()
export class BooksService {
  static smartModule = smartModule({
    smartImports: [UsersService.smartModule, DatabaseService.smartModule],
    providers: [BooksService],
    exports: [BooksService],
  })
  constructor(
    private readonly usersService: UsersService,
    private readonly dbService: DatabaseService,
  ) {}
}

// 4. The root module.
@Module({
  // By importing BooksService, we also implicitly import its dependencies.
  // The library gathers all configuration requirements, so we only need to
  // provide the `url` for the deeply nested DatabaseService here.
  imports: [BooksService.smartModule({ url: 'postgres://my-app-db' })],
})
export class AppModule {}
Copy

In this example, AppModule only configures BooksService. The library automatically merges the requirements from BooksService and UsersService, recognizes that both need DatabaseService with a url, and passes the single url to both instances. This prevents configuration duplication and simplifies dependency management.

Advanced: Namespacing Composed Modules

You can apply a label or prefix to an entire smartImport to namespace the complete configuration tree. This is useful when integrating complex third-party smart modules to avoid configuration key collisions.

Example:

// 1. Define the dependency services and their configs.
export class LoggerConfig {
  log_level: string
}
@Injectable()
export class LoggerService {
  static smartModule = smartModule({
    smartConfigs: [LoggerConfig],
    providers: [LoggerService],
    exports: [LoggerService],
  })
  constructor(private readonly config: LoggerConfig) {}
}

export class MetricsConfig {
  metrics_url: string
}
@Injectable()
export class MetricsService {
  static smartModule = smartModule({
    smartConfigs: [MetricsConfig],
    providers: [MetricsService],
    exports: [MetricsService],
  })
  constructor(private readonly config: MetricsConfig) {}
}

// 2. This third-party service bundles its own dependencies.
@Injectable()
export class ThirdPartyAnalyticsService {
  static smartModule = smartModule({
    smartImports: [LoggerService.smartModule, MetricsService.smartModule],
    providers: [ThirdPartyAnalyticsService],
    exports: [ThirdPartyAnalyticsService],
  })
  constructor(
    private readonly logger: LoggerService,
    private readonly metrics: MetricsService,
  ) {}
}

// 3. To avoid potential configuration conflicts, we wrap its import with a label.
@Injectable()
export class AppService {
  static smartModule = smartModule({
    smartImports: [
      {
        smartImport: ThirdPartyAnalyticsService.smartModule,
        label: 'analytics' as const,
      },
    ],
    providers: [AppService],
    exports: [AppService],
  })
  constructor(private readonly analyticsService: ThirdPartyAnalyticsService) {}
}

@Module({
  imports: [
    // Now, the entire configuration for the third-party module and all of its
    // dependencies is nested under the 'analytics' key.
    AppService.smartModule({
      analytics: {
        log_level: 'debug',
        metrics_url: 'http://metrics.service.com',
      },
    }),
  ],
})
export class AppModule {}
Copy

Instance Semantics

Every call to a smart module factory creates its own DynamicModule — and therefore its own provider instances. In the composition example above, BooksService and UsersService each import DatabaseService.smartModule, so the application ends up with two independent DatabaseService instances receiving the same merged configuration. "Configured once" applies to configuration, not to instances.

This holds on every supported NestJS major (verified on 10 and 11 under both module id algorithms — see spec/module-identity.spec.ts): the generated module classes are unique per call, so NestJS never deduplicates them.

Practical consequences:

• Stateless services are unaffected — extra instances are cheap.
• Stateful services (connection pools, caches) are created once per importing branch. If a single shared instance matters, create the DynamicModule once and reuse the same object reference (NestJS deduplicates modules by reference), or provide the service through a global: true module — see the Global Configuration recipe.

Advanced Usage

Using Injection Tokens

Configuration uses its class as the injection token by default. You can override this with custom string or symbol tokens to avoid class-based injection or conflicts.

Note: The token option is only available for smartConfigs, not for smartImports.

Example: Inline Token

// redis.service.ts
import { Inject, Injectable } from '@nestjs/common'
import { smartModule } from 'nestjs-smart-modules'

export class RedisConfig {
  host: string
  port: number
}
export const REDIS_CONFIG_TOKEN = 'REDIS_CONFIG'

@Injectable()
export class RedisService {
  static smartModule = smartModule({
    smartConfigs: [{ smartConfig: RedisConfig, token: REDIS_CONFIG_TOKEN }],
    providers: [RedisService],
    exports: [RedisService],
  })

  constructor(@Inject(REDIS_CONFIG_TOKEN) private readonly config: RedisConfig) {}
}
Copy

Example: Static Token on Config Class

// notifications.config.ts
export class NotificationsConfig {
  static token = 'NOTIFICATIONS_CONFIG' // Static token
  apiKey: string
}

// notifications.service.ts
import { Inject, Injectable } from '@nestjs/common'
import { smartModule } from 'nestjs-smart-modules'
import { NotificationsConfig } from './notifications.config.ts'

@Injectable()
export class NotificationsService {
  static smartModule = smartModule({
    smartConfigs: [NotificationsConfig],
    providers: [NotificationsService],
    exports: [NotificationsService],
  })

  constructor(@Inject(NotificationsConfig.token) private readonly config: NotificationsConfig) {}
}
Copy

Note: A static token on a config class will be overridden if you provide a token property inline where the class is used.

Asynchronous Configuration

Recommendation: Use synchronous configuration whenever possible. Only use async configuration for exceptional cases when config must be loaded from a running NestJS provider.

For exceptional cases where synchronous setup isn't possible, smartModule can handle asynchronous configuration. This is useful when integrating with legacy modules or when configuration comes from running NestJS providers.

Example:

Imagine you have a ConfigModule that asynchronously provides a ConfigService.

// auth.service.ts
import { Injectable } from '@nestjs/common'
import { smartModule } from 'nestjs-smart-modules'

export class AuthConfig {
  jwtSecret: string
  expiresIn: string
}

@Injectable()
export class AuthService {
  static smartModule = smartModule({
    smartConfigs: [AuthConfig],
    providers: [AuthService],
    exports: [AuthService],
  })

  constructor(private readonly config: AuthConfig) {}
}

// app.module.ts
import { Module } from '@nestjs/common'
import { ConfigModule, ConfigService } from '@nestjs/config'
import { AuthService } from './auth.service'

@Module({
  imports: [
    ConfigModule.forRoot(), // Standard NestJS ConfigModule
    AuthService.smartModule({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (configService: ConfigService) => ({
        jwtSecret: configService.getOrThrow('JWT_SECRET'),
        expiresIn: configService.getOrThrow('JWT_EXPIRES_IN'),
      }),
    }),
  ],
})
export class AppModule {}
Copy

Module Definition Factory

The factory pattern provides an "escape hatch" when module definitions depend on resolved configuration values. Use this only when static module definitions aren't sufficient.

Common use cases include:

• Dynamic Provider Values: Creating a provider whose useValue is derived from one or more configuration properties.
• Conditional Providers: Conditionally registering a provider based on a flag in the configuration (e.g., enabling a MockService for testing).
• Wrapping Third-Party Modules: Dynamically importing and configuring a third-party module (e.g., @nestjs/jwt) using values from your smart configuration.
• Dynamic Imports: Conditionally importing other modules based on the configuration.
• Re-exporting Dependencies: Gaining access to the dynamically created configuration modules to re-export them, making them available to other modules that import your smart module.

While you can pass configurations as inline arguments, the recommended pattern is to use the smartConfigs and smartImports properties inside the module definition object for better clarity. The primary use case for passing configs as inline arguments is to use them with this factory pattern.

Signature:

smartModule(
  ...configs: AnySmartConfig[], // Passed inline for factory access
  factory: (imports: DynamicModule[], ...instantiatedConfigs: object[]) => SmartModule
)
Copy

Use Case: Dynamic Provider Values

The most common reason to use the factory pattern is to create providers whose definitions depend on the values from your configuration. Because the factory function only runs after the DatabaseConfig has been instantiated, you can access its properties.

Note: For this pattern to work, configuration classes must be passed as inline arguments to smartModule, not inside the smartConfigs property. This is only available during synchronous module creation.

Example:

import { Inject, Injectable } from '@nestjs/common'
import { smartModule } from 'nestjs-smart-modules'

export class ReportingConfig {
  apiUrl: string
}

@Injectable()
export class ReportingService {
  static smartModule = smartModule(
    ReportingConfig, // Passed inline to be available in the factory
    (imports, reportingConfig: ReportingConfig) => ({
      imports,
      providers: [
        ReportingService,
        {
          provide: 'REPORTING_SERVICE_URL',
          // Use the config value at definition time
          useValue: `${reportingConfig.apiUrl}/reports`,
        },
      ],
      exports: [ReportingService],
    }),
  )

  constructor(@Inject('REPORTING_SERVICE_URL') private readonly reportingUrl: string) {}
}

@Module({
  imports: [
    ReportingService.smartModule({
      apiUrl: 'http://api.service.com',
    }),
  ],
})
export class AppModule {}
Copy

Use Case: Wrapping a Third-Party Module

The factory pattern is especially powerful when you need to wrap a traditional NestJS module that uses a standard .forRoot() or .register() configuration pattern. This allows you to integrate third-party modules into your smartModule ecosystem seamlessly.

By using the factory, you can instantiate your configuration class first and then pass its values to the third-party module's configuration method.

Example: Wrapping JwtModule

import { Injectable } from '@nestjs/common'
import { smartModule } from 'nestjs-smart-modules'
import { JwtModule } from '@nestjs/jwt'

// 1. Define the configuration for the third-party module.
export class JwtConfig {
  secret: string
  signOptions: { expiresIn: string }
}

// 2. Create a wrapper service.
@Injectable()
export class JwtWrapperService {
  static smartModule = smartModule(
    JwtConfig, // Pass config inline to access it in the factory.
    (imports, jwtConfig: JwtConfig) => {
      // 3. Dynamically register the third-party module using the config.
      const jwtModule = JwtModule.register({
        secret: jwtConfig.secret,
        signOptions: jwtConfig.signOptions,
      })

      return {
        imports: [...imports, jwtModule],
        providers: [JwtWrapperService],
        // 4. Export both your service and the third-party module.
        exports: [JwtWrapperService, jwtModule],
      }
    },
  )
}

// 5. Use the wrapper service in your application.
@Module({
  imports: [
    JwtWrapperService.smartModule({
      secret: 'your-secret-key',
      signOptions: { expiresIn: '60s' },
    }),
  ],
})
export class AppModule {}
Copy

This pattern allows any other service that imports JwtWrapperService.smartModule to inject NestJS's JwtService directly, without needing to know about the underlying configuration details.

Use Case: Re-exporting Dependencies

The first argument to the factory function, imports, is an array of DynamicModule instances. These modules are automatically generated by smartModule for each inline SmartConfig class that you provided.

Each of these dynamic modules is responsible for providing one of your configured dependencies. For example, if you pass DatabaseConfig as an inline smart config, one of the modules in the imports array will be the one that provides the configured instance of DatabaseConfig.

While smartModule automatically adds this imports array to the imports array of the final module it creates, you might want to access it for advanced use cases, such as re-exporting the modules.

Example:

import { Injectable } from '@nestjs/common'
import { smartModule } from 'nestjs-smart-modules'

export class DatabaseConfig {
  url: string
}
export class CacheConfig {
  host: string
}

@Injectable()
export class MyService {
  static smartModule = smartModule(
    DatabaseConfig, // Pass SmartConfig classes inline
    CacheConfig,
    imports => ({
      providers: [MyService],
      // You can now access the created modules for DatabaseConfig and CacheConfig
      // and re-export them.
      exports: [MyService, ...imports],
    }),
  )
}

@Module({
  imports: [
    MyService.smartModule({
      url: 'postgres://localhost:5432',
      host: 'redis://localhost:6379',
    }),
  ],
})
export class AppModule {}
Copy

Recipes

This section covers advanced patterns and solutions to common problems.

Creating and Using Multiple Instances of a Module

The Challenge: With static @Module classes, importing the same module everywhere yields one shared provider instance. Smart module factories already create separate instances per call (see Instance Semantics) — but those instances are anonymous and interchangeable. For primary/replica-style setups you need separate instances that are individually addressable and configurable; that is what this recipe provides.

The Solution: A Labeled Module Factory

Create a static factory function on your service class that generates uniquely-provided, labeled modules. This encapsulates the complexity and provides a clean API using smartImports and smartConfigs.

Step 1: Enhance the Base Service

Add three static helper methods to your DatabaseService class:

1. getTokenForLabel(label: string): A public method that creates a predictable, unique injection token.
2. Inject(label: string): A decorator that simplifies injecting the service with a specific label.
3. smartModuleCustom(label: string): A factory that returns a smartModule that provides the DatabaseService under a unique token.

// database.service.ts
import { Inject, Injectable } from '@nestjs/common'
import { smartModule } from 'nestjs-smart-modules'

export class DatabaseConfig {
  url: string
}

@Injectable()
export class DatabaseService {
  // The base smartModule for a single, default instance.
  static smartModule = smartModule({
    smartConfigs: [DatabaseConfig],
    providers: [DatabaseService],
    exports: [DatabaseService],
  })

  static getTokenForLabel(label: string) {
    return `${label.toUpperCase()}_DATABASE_SERVICE`
  }

  static Inject = (label: string) => Inject(DatabaseService.getTokenForLabel(label))

  static smartModuleCustom = function (this: typeof DatabaseService, label: string) {
    const token = this.getTokenForLabel(label)

    return smartModule({
      smartConfigs: [DatabaseConfig],
      providers: [
        DatabaseService, // Provide the base service...
        {
          provide: token,
          useClass: DatabaseService, // ...and create a new instance for the unique token.
        },
      ],
      exports: [token],
    })
  }

  constructor(private readonly config: DatabaseConfig) {}

  find(query: string) {
    return `${this.config.url} for ${query}`
  }
}
Copy

Step 2: Create a Higher-Level Service

Create a higher-level service that consumes the uniquely provided database instances and encapsulates its own dependencies with its own smartModule.

graph TD
    App["AppModule"] --> DBSvc["DatabasesService"]
    DBSvc --> Primary["DatabaseService<br/>(labeled: 'primary')"]
    DBSvc --> Replica["DatabaseService<br/>(labeled: 'replica')"]
    Primary --> PrimaryConfig["DatabaseConfig"]
    Replica --> ReplicaConfig["DatabaseConfig"]

    Config["Configuration Object<br/>{ primary: { url: 'postgres://primary-db' }, replica: { url: 'postgres://replica-db' } }"] --> App
    Config -.->|"primary.url"| PrimaryConfig
    Config -.->|"replica.url"| ReplicaConfig

    style App fill:#fff3e0
    style DBSvc fill:#e8f5e8
    style Primary fill:#e3f2fd
    style Replica fill:#f3e5f5
    style PrimaryConfig fill:#e8eaf6
    style ReplicaConfig fill:#fce4ec
    style Config fill:#fff8e1
Copy

// databases.service.ts
import { Injectable } from '@nestjs/common'
import { DatabaseService } from './database.service'
import { smartModule } from 'nestjs-smart-modules'

@Injectable()
export class DatabasesService {
  // This service becomes a self-contained smart module.
  static smartModule = smartModule({
    // It declares its dependencies on the labeled database modules.
    smartImports: [
      {
        smartImport: DatabaseService.smartModuleCustom('primary'),
        label: 'primary' as const,
      },
      {
        smartImport: DatabaseService.smartModuleCustom('replica'),
        label: 'replica' as const,
      },
    ],
    providers: [DatabasesService],
    exports: [DatabasesService],
  })

  constructor(
    @DatabaseService.Inject('primary')
    private readonly primaryDb: DatabaseService,
    @DatabaseService.Inject('replica')
    private readonly replicaDb: DatabaseService,
  ) {}

  // Example method that uses both database connections.
  find(query: string) {
    return [this.primaryDb.find(query), this.replicaDb.find(query)]
  }
}
Copy

Step 3: Compose the Application

The final application composition becomes simple. Just import DatabasesService.smartModule and provide the expected configuration object.

// app.module.ts
import { Module } from '@nestjs/common'
import { DatabasesService } from './databases.service'

@Module({
  imports: [
    // Import the top-level service and provide the combined config.
    DatabasesService.smartModule({
      primary: {
        url: 'postgres://primary-db',
      },
      replica: {
        url: 'postgres://replica-db',
      },
    }),
  ],
})
export class AppModule {}
Copy

Creating a Global Configuration Module (the forRoot pattern)

When to use this pattern: While this pattern is powerful, it's important to understand its place. If you are building an entire application from the ground up with nestjs-smart-modules, you typically do not need a .forRoot() module. The recommended approach is to build a dependency tree and provide a single configuration object to your root AppModule, as described in the Module Composition section.

This forRoot pattern is most useful in two scenarios:

1. Incremental Adoption: When you want to introduce nestjs-smart-modules into an existing, traditional NestJS application.
2. Creating Standalone Libraries: If you are building a reusable library for others to consume, providing a familiar .forRoot() method for configuration is a common and well-understood convention.

A common requirement is having a single, globally available configuration that any service can access without importing specific modules everywhere. Traditional NestJS uses .forRoot() static methods. You can achieve the same result cleanly with smartModule.

Step 1: Define the Global Configuration and Module

Create GlobalConfig class and GlobalConfigModule that provides it globally. Use the factory pattern with smartModule to re-export the configuration module.

// global-config.module.ts
import { Injectable } from '@nestjs/common'
import { smartModule } from 'nestjs-smart-modules'

// Define the shape of your global configuration.
export class GlobalConfig {
  appName: string
  isProduction: boolean
}

// Create a self-contained module for the config.
@Injectable()
export class GlobalConfigModule {
  // Use smartModule to create a configurable, global module.
  static forRoot = smartModule(GlobalConfig, imports => ({
    global: true, // This makes the providers available everywhere.
    exports: imports,
    // exports: [GlobalConfig], // will not work because smart config not injected into a smart module but into a new module that goes into imports array, we cant export others module exports only re export whole imported module
  }))
}
Copy

Step 2: Inject the Global Config in a Feature Service

Any service can now inject GlobalConfig directly. This service demonstrates using configuration in business logic.

// feature.service.ts
import { Injectable } from '@nestjs/common'
import { GlobalConfig } from './global-config.module'

@Injectable()
export class FeatureService {
  constructor(private readonly config: GlobalConfig) {}

  doSomething() {
    if (!this.config.isProduction) {
      return 'not production'
    }

    return 'production'
  }
}
Copy

Step 3: Provide the Configuration in AppModule

Create AppModule using smartModule that imports global configuration. Demonstrates synchronous configuration pattern.

// app.module.ts
import { smartModule } from 'nestjs-smart-modules'
import { GlobalConfigModule } from './global-config.module'
import { FeatureService } from './feature.service'

export class AppModule {
  static smartModule = smartModule({
    imports: [
      GlobalConfigModule.forRoot({
        appName: 'My Awesome App',
        isProduction: true,
      }),
    ],
    providers: [FeatureService],
  })
}
Copy

This pattern provides clean, type-safe global configuration management using the factory pattern with smartModule. The global flag makes configuration available throughout the application.

Asynchronous Configuration

The factory pattern supports asynchronous configuration using standard useFactory pattern. This example integrates with NestJS's ConfigModule for environment-based configuration.

Example:

// async-app.module.ts
import { ConfigModule, ConfigService } from '@nestjs/config'
import { smartModule } from 'nestjs-smart-modules'
import { GlobalConfigModule } from './global-config.module'
import { FeatureService } from './feature.service'

export class AsyncAppModule {
  static smartModule = smartModule({
    imports: [
      ConfigModule.forRoot({ isGlobal: true }), // Make the standard ConfigService available
      GlobalConfigModule.forRoot({
        imports: [ConfigModule],
        inject: [ConfigService],
        useFactory: (configService: ConfigService) => ({
          appName: configService.get('APP_NAME') || 'My Async App',
          isProduction: configService.get('NODE_ENV') === 'production',
        }),
      }),
    ],
    providers: [FeatureService],
  })
}
Copy

Why Not ConfigurableModuleBuilder?

NestJS ships ConfigurableModuleBuilder for building configurable modules, and it is a fine choice for a single module with options. smartModule targets a different problem — composing an application out of many configurable pieces:

If you maintain one standalone library module with a forRoot(), the builder is enough. If you are assembling an application from composable blocks with centralized, fully typed configuration — that is what this library is for.

API Reference

The generated API reference (from the JSDoc in the sources) lives at webwayer.github.io/nestjs-smart-modules.

smartModule() Function

The core function that transforms your service into a configurable module factory.

Signature:

smartModule(definition: SmartModuleDefinition): (config: object) => DynamicModule
Copy

Parameters:

• definition - Object containing module definition and smart configurations

SmartModuleDefinition Interface:

interface SmartModuleDefinition {
  // Standard NestJS DynamicModule properties
  module?: any // Default: the service class itself
  imports?: any[]
  controllers?: any[]
  providers?: any[]
  exports?: any[]
  global?: boolean

  // Smart module specific properties
  smartConfigs?: SmartConfig[] // Configuration classes
  smartImports?: SmartImport[] // Other smart modules to import
}
Copy

SmartConfig Options:

type SmartConfig =
  | ConfigClass // Simple config class
  | {
      // Advanced config options
      smartConfig: ConfigClass
      label?: string // Namespace under nested object
      prefix?: string // Prefix all properties
      token?: string | symbol // Custom injection token
    }
Copy

SmartImport Options:

type SmartImport =
  | SmartModuleFactory // Simple import
  | {
      // Advanced import options
      smartImport: SmartModuleFactory
      label?: string // Namespace configuration
      prefix?: string // Prefix configuration
    }
Copy

Configuration Class Requirements

Configuration classes should follow these patterns:

export class MyConfig {
  // Required properties
  requiredProp: string

  // Optional properties
  optionalProp?: string

  // Properties with defaults (must be optional!)
  defaultProp?: number = 42

  // Static configuration
  static label?: string = 'myConfig'
  static prefix?: string = 'my_'
  static token?: string = 'MY_CONFIG_TOKEN'
}
Copy

Factory Pattern

For advanced use cases where module definition depends on configuration values:

smartModule(
  ...configs: ConfigClass[],
  factory: (imports: DynamicModule[], ...configs: object[]) => SmartModuleDefinition
): (config: object) => DynamicModule
Copy

Asynchronous Configuration

For cases requiring async configuration:

MyService.smartModule({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (configService: ConfigService) => ({
    // Return your configuration object
  }),
})
Copy