NestJS Enterprise Backend APIs · درس

إنشاء وحدات ديناميكية قابلة للتهيئة

إنشاء موفّري forRoot وforRootAsync باستخدام ConfigurableModuleBuilder لبناء وحدات مستأجرين قابلة لإعادة الاستخدام.

إنشاء وحدات ديناميكية قابلة للتهيئة درس مجاني في NestJS Enterprise Backend APIs على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في NestJS Enterprise Backend APIs، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة NestJS Enterprise Backend APIs 4 دروس في المجموع.

بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.

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?

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.

الأسئلة الشائعة

هل درس «إنشاء وحدات ديناميكية قابلة للتهيئة» مجاني؟

نعم — نص درس «إنشاء وحدات ديناميكية قابلة للتهيئة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة NestJS Enterprise Backend APIs، انتقل إلى CoddyKit PRO. تتضمن دورة NestJS Enterprise Backend APIs 4 دروس في المجموع.

ماذا ستتعلم في «إنشاء وحدات ديناميكية قابلة للتهيئة»؟

إنشاء موفّري forRoot وforRootAsync باستخدام ConfigurableModuleBuilder لبناء وحدات مستأجرين قابلة لإعادة الاستخدام. تتمرن على NestJS Enterprise Backend APIs مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ NestJS Enterprise Backend APIs؟

لا تُشترط خبرة سابقة. NestJS Enterprise Backend APIs على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «إنشاء وحدات ديناميكية قابلة للتهيئة»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس NestJS Enterprise Backend APIs هذا؟

نعم. كل درس في NestJS Enterprise Backend APIs يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

تحديد المستأجر عبر Middleware وAsyncLocalStorage
اتصالات قاعدة بيانات بمخطط لكل مستأجر
إنشاء وحدات ديناميكية قابلة للتهيئة
الموفّرون المرتبطون بنطاق الطلب ومقايضاتهم

← العودة إلى NestJS Enterprise Backend APIs