PricingLoginStart free
NestJS Enterprise Backend APIs · Lezione

Creazione di moduli dinamici configurabili

Definisca provider forRoot e forRootAsync con ConfigurableModuleBuilder per creare moduli riutilizzabili per i tenant.

Lezione 3 di 413 passaggi

Creazione di moduli dinamici configurabili è una lezione NestJS Enterprise Backend APIs gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento NestJS Enterprise Backend APIs, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso NestJS Enterprise Backend APIs include 4 lezioni in totale.

Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.

Why Dynamic Modules?

A regular NestJS module exports a fixed set of providers. But a reusable module — like a tenant resolver, a cache client, or an HTTP wrapper — needs configuration from the consumer: a connection string, an API key, a tenant strategy.

A dynamic module is a module whose providers, imports, and exports are computed at import time from caller-supplied options. The convention is a static factory method, almost always named forRoot() (or register()), that returns a DynamicModule object.

  • forRoot() — configure once, globally (DB, tenant registry)
  • register() — configure per-import, possibly multiple times
  • forFeature() — register feature-scoped sub-resources

The DynamicModule Shape

A static factory must return an object matching the DynamicModule interface. The key extra field is module, which points back to the host class. Everything else mirrors a normal @Module() decorator.

Here a TenantModule.forRoot() turns caller options into a provider keyed by a token, then exports it so other modules can inject it.

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

export interface TenantOptions {
  registryUrl: string;
  defaultTenant: string;
}

export const TENANT_OPTIONS = 'TENANT_OPTIONS';

@Module({})
export class TenantModule {
  static forRoot(options: TenantOptions): DynamicModule {
    return {
      module: TenantModule,
      providers: [{ provide: TENANT_OPTIONS, useValue: options }],
      exports: [TENANT_OPTIONS],
    };
  }
}

Consuming forRoot

The consumer imports the dynamic module by calling the factory, not just referencing the class. The returned options provider becomes injectable anywhere inside the module's scope.

A service injects the TENANT_OPTIONS token to read its configuration.

import { Inject, Injectable, Module } from '@nestjs/common';
import { TenantModule, TENANT_OPTIONS, TenantOptions } from './tenant.module';

@Injectable()
export class TenantService {
  constructor(@Inject(TENANT_OPTIONS) private readonly opts: TenantOptions) {}

  resolve(header?: string): string {
    return header ?? this.opts.defaultTenant;
  }
}

@Module({
  imports: [
    TenantModule.forRoot({
      registryUrl: 'https://registry.internal/tenants',
      defaultTenant: 'acme',
    }),
  ],
})
export class AppModule {}

The Problem: Async Configuration

Synchronous forRoot(options) works only when you already hold the literal values. In real backends the registryUrl lives in ConfigService, a secrets manager, or another async source.

That is why reusable modules expose a second factory: forRootAsync(). It lets the caller provide options via useFactory, useClass, or useExisting — and crucially, to inject other providers that resolve the values.

  • useFactory — inline async function returning the options
  • useClass / useExisting — a class implementing an options factory interface

Hand-Rolled forRootAsync

Before reaching for helpers, it is worth seeing the mechanics. forRootAsync accepts an async-options object, declares an imports list (so ConfigModule is visible), and wires the caller's useFactory into the options provider.

The factory's inject array feeds dependencies into useFactory, exactly like any provider.

import { DynamicModule, Module, Provider } from '@nestjs/common';
import { TenantOptions, TENANT_OPTIONS } from './tenant.module';

export interface TenantAsyncOptions {
  imports?: any[];
  inject?: any[];
  useFactory: (...args: any[]) => Promise<TenantOptions> | TenantOptions;
}

@Module({})
export class TenantModule {
  static forRootAsync(async: TenantAsyncOptions): DynamicModule {
    const optionsProvider: Provider = {
      provide: TENANT_OPTIONS,
      useFactory: async.useFactory,
      inject: async.inject ?? [],
    };
    return {
      module: TenantModule,
      imports: async.imports ?? [],
      providers: [optionsProvider],
      exports: [TENANT_OPTIONS],
    };
  }
}

Calling forRootAsync

Now the consumer pulls values from ConfigService at runtime. The imports field makes ConfigModule available inside the dynamic module so the factory can inject ConfigService.

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TenantModule } from './tenant.module';

@Module({
  imports: [
    ConfigModule.forRoot(),
    TenantModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        registryUrl: config.getOrThrow<string>('TENANT_REGISTRY_URL'),
        defaultTenant: config.get<string>('DEFAULT_TENANT', 'acme'),
      }),
    }),
  ],
})
export class AppModule {}

Enter ConfigurableModuleBuilder

Writing both factories by hand is boilerplate that every reusable module repeats. Since NestJS 9, ConfigurableModuleBuilder generates the forRoot/forRootAsync plumbing for you from a single options type.

You create a small *.module-definition.ts file that calls the builder and exports:

  • ConfigurableModuleClass — a base class your module extends
  • MODULE_OPTIONS_TOKEN — the injection token for the resolved options
  • OPTIONS_TYPE / ASYNC_OPTIONS_TYPE — typed signatures for the generated methods

Defining the Module Definition

The builder is generic over your options interface. Calling .build() returns everything the module needs. Your module then extends ConfigurableModuleClass and instantly gains forRoot() and forRootAsync().

import { ConfigurableModuleBuilder } from '@nestjs/common';

export interface TenantModuleOptions {
  registryUrl: string;
  defaultTenant: string;
}

export const {
  ConfigurableModuleClass,
  MODULE_OPTIONS_TOKEN,
  OPTIONS_TYPE,
  ASYNC_OPTIONS_TYPE,
} = new ConfigurableModuleBuilder<TenantModuleOptions>().build();

Wiring the Module Class

The host module extends the generated base class and registers its real providers. Services inject MODULE_OPTIONS_TOKEN to read the resolved options — whether they came from forRoot or forRootAsync, the token is the same.

Note: when you add your own providers/exports alongside the generated ones, keep the @Module() decorator — the builder merges its dynamic part with your static metadata.

import { Module } from '@nestjs/common';
import {
  ConfigurableModuleClass,
  MODULE_OPTIONS_TOKEN,
} from './tenant.module-definition';
import { TenantService } from './tenant.service';

@Module({
  providers: [TenantService],
  exports: [TenantService, MODULE_OPTIONS_TOKEN],
})
export class TenantModule extends ConfigurableModuleClass {}

Custom Method Name & Extra Options

The builder is configurable. Use .setClassMethodName('register') when per-import registration reads better than forRoot. Use .setExtras() to add fields that are not part of the injected options — typically isGlobal — and a transform that injects them into the DynamicModule (e.g. setting global: true).

import { ConfigurableModuleBuilder } from '@nestjs/common';
import { TenantModuleOptions } from './tenant.types';

export interface TenantExtras {
  isGlobal?: boolean;
}

export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
  new ConfigurableModuleBuilder<TenantModuleOptions>()
    .setExtras<TenantExtras>(
      { isGlobal: false },
      (definition, extras) => ({
        ...definition,
        global: extras.isGlobal,
      }),
    )
    .setClassMethodName('register')
    .build();

Multi-Tenancy Payoff

Put together, a tenant module becomes a drop-in dependency for any service in the platform. A request-scoped provider can resolve the active tenant from a header, falling back to the configured default — all driven by options the consuming app supplied via register/registerAsync.

The key insight: configuration flows through one token (MODULE_OPTIONS_TOKEN), so internal services never care whether setup was sync or async, literal or factory-resolved.

import { Inject, Injectable, Scope } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';
import { Request } from 'express';
import { MODULE_OPTIONS_TOKEN } from './tenant.module-definition';
import { TenantModuleOptions } from './tenant.types';

@Injectable({ scope: Scope.REQUEST })
export class TenantContext {
  constructor(
    @Inject(MODULE_OPTIONS_TOKEN) private readonly opts: TenantModuleOptions,
    @Inject(REQUEST) private readonly req: Request,
  ) {}

  get tenantId(): string {
    const header = this.req.headers['x-tenant-id'];
    return (Array.isArray(header) ? header[0] : header) ?? this.opts.defaultTenant;
  }
}

Quick Check

Your reusable TenantModule must read its registryUrl from ConfigService, which itself loads asynchronously at bootstrap. Which approach lets the consumer wire this correctly?

Rispondi nella lezione interattiva

Recap

You built a configurable dynamic module end to end:

  • A dynamic module returns a DynamicModule from a static factory (forRoot/register), turning caller options into a token-backed provider.
  • forRootAsync adds imports, inject, and useFactory so options can be resolved from ConfigService or other async sources.
  • ConfigurableModuleBuilder generates both factories from one options type, exposing ConfigurableModuleClass and MODULE_OPTIONS_TOKEN.
  • .setClassMethodName() renames the factory; .setExtras() adds out-of-band flags like isGlobal.
  • All internal services inject the same options token, staying agnostic to how configuration was supplied — the foundation for reusable multi-tenant modules.
Gratis per iniziare

Impara TypeScript con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi
20
Lezioni
76
Inizia a imparare gratisVisualizza il corso completo

Domande Frequenti

La lezione «Creazione di moduli dinamici configurabili» è gratuita?

Sì — il testo completo di «Creazione di moduli dinamici configurabili» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso NestJS Enterprise Backend APIs, passa a CoddyKit PRO. Il corso NestJS Enterprise Backend APIs include 4 lezioni in totale.

Cosa imparerò in «Creazione di moduli dinamici configurabili»?

Definisca provider forRoot e forRootAsync con ConfigurableModuleBuilder per creare moduli riutilizzabili per i tenant. Eserciti NestJS Enterprise Backend APIs con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare NestJS Enterprise Backend APIs?

Non è richiesta alcuna esperienza precedente. NestJS Enterprise Backend APIs su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «Creazione di moduli dinamici configurabili»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione NestJS Enterprise Backend APIs?

Sì. Ogni lezione NestJS Enterprise Backend APIs include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Risoluzione del tenant tramite middleware e AsyncLocalStorage
  2. Connessioni al database con uno schema per tenant
  3. Creazione di moduli dinamici configurabili
  4. Provider con ambito per richiesta e relativi compromessi
← Torna a NestJS Enterprise Backend APIs