Defining dynamic modules

August 15, 2022

So far in this series, we’ve defined many different modules that can group provides and controllers. None of them was customizable, though. In this article, we learn how to create dynamic modules that are customizable, making them easier to reuse. While doing that, we rewrite some of our old code to use dynamic modules.

To better illustrate why we might want to use dynamic modules, let’s look at an EmailModule for sending scheduled emails with cron and Nodemailer.

email.module.ts#

import { Module } from "@nestjs/common"
import EmailService from "./email.service"
import { ConfigModule } from "@nestjs/config"
@Module({
  imports: [ConfigModule],
  controllers: [],
  providers: [EmailService],
  exports: [EmailService],
})
export class EmailModule {}

The above module contains the EmailService provider and exports it. Let’s look under the hood:

email.service.ts#

import { Injectable } from "@nestjs/common"
import { createTransport } from "nodemailer"
import * as Mail from "nodemailer/lib/mailer"
import { ConfigService } from "@nestjs/config"
@Injectable()
export default class EmailService {
  private nodemailerTransport: Mail
  constructor(private readonly configService: ConfigService) {
    this.nodemailerTransport = createTransport({
      service: configService.get("EMAIL_SERVICE"),
      auth: {
        user: configService.get("EMAIL_USER"),
        pass: configService.get("EMAIL_PASSWORD"),
      },
    })
  }
  sendMail(options: Mail.Options) {
    return this.nodemailerTransport.sendMail(options)
  }
}

The crucial thing to notice above is that our EmailService will always have the same configuration. So, for example, we can’t have a separate email for password confirmation and a separate email for the newsletter. To deal with this issue, we can create a dynamic module.

Creating a dynamic module#

To create a dynamic module, let’s add a static method to the EmailModule.

email.module.ts#

import { DynamicModule, Module } from "@nestjs/common"
import EmailService from "./email.service"
import { EMAIL_CONFIG_OPTIONS } from "./constants"
import EmailOptions from "./emailOptions.interface"
@Module({})
export class EmailModule {
  static register(options: EmailOptions): DynamicModule {
    return {
      module: EmailModule,
      providers: [
        {
          provide: EMAIL_CONFIG_OPTIONS,
          useValue: options,
        },
        EmailService,
      ],
      exports: [EmailService],
    }
  }
}

Above, instead of putting our module definition inside the @Module({}) decorator, we return it from the register method. We allow the user to provide the EmailOptions as the argument to the register function.

emailOptions.interface.ts#

interface EmailOptions {
  service: string
  user: string
  password: string
}
export default EmailOptions

We also define a unique EMAIL_CONFIG_OPTIONS constant in a separate file.

constants.ts#

export const EMAIL_CONFIG_OPTIONS = "EMAIL_CONFIG_OPTIONS"

We can also use a Symbol.

In the register() method, we add the EMAIL_CONFIG_OPTIONS to the list of providers along with the option’s value. Thanks to the above, the configuration will be available in the EmailService through the @Inject() decorator.

email.service.ts#

import { Inject, Injectable } from "@nestjs/common"
import { createTransport } from "nodemailer"
import { EMAIL_CONFIG_OPTIONS } from "./constants"
import Mail from "nodemailer/lib/mailer"
import EmailOptions from "./emailOptions.interface"
@Injectable()
export default class EmailService {
  private nodemailerTransport: Mail
  constructor(@Inject(EMAIL_CONFIG_OPTIONS) private options: EmailOptions) {
    this.nodemailerTransport = createTransport({
      service: options.service,
      auth: {
        user: options.user,
        pass: options.password,
      },
    })
  }
  sendMail(options: Mail.Options) {
    return this.nodemailerTransport.sendMail(options)
  }
}

Thanks to our approach, we can now configure the module when importing it.

emailConfirmation.module.ts#

import { Module } from "@nestjs/common"
import { EmailConfirmationService } from "./emailConfirmation.service"
import { ConfigModule } from "@nestjs/config"
import { EmailModule } from "../email/email.module"
import { JwtModule } from "@nestjs/jwt"
import { EmailConfirmationController } from "./emailConfirmation.controller"
import { UsersModule } from "../users/users.module"
@Module({
  imports: [
    ConfigModule,
    EmailModule.register({
      service: "gmail",
      user: "email.account@gmail.com",
      password: "mystrongpassword",
    }),
    JwtModule.register({}),
    UsersModule,
  ],
  providers: [EmailConfirmationService],
  exports: [EmailConfirmationService],
  controllers: [EmailConfirmationController],
})
export class EmailConfirmationModule {}

Asynchronous configuration#

There is a significant drawback to the above approach because we no longer can use the ConfigService when setting up our email provider. Fortunately, we can deal with this issue by creating an asynchronous version of our register method. It will have access to the dependency injection mechanism built into NestJS.

Our registerAsync method will also receive the options, but the type used for its argument is slightly different than register.

EmailModule.registerAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (configService: ConfigService) => ({
    service: configService.get('EMAIL_SERVICE'),
    user: configService.get('EMAIL_USER'),
    password: configService.get('EMAIL_PASSWORD'),
  }),
}),

Let’s go through all of the properties above:

imports – a list of modules we want the EmailModule to import because we need them in useFactory,
inject – a list of providers we want NestJS to inject into the context of the useFactory function,
useFactory – a function that returns the value for our EMAIL_CONFIG_OPTIONS provider.

A straightforward way to create a type with the above properties is to use the ModuleMetadata and FactoryProvider interfaces.

emailOptions.type.ts#

import { ModuleMetadata } from "@nestjs/common"
import { FactoryProvider } from "@nestjs/common/interfaces/modules/provider.interface"
 
import EmailOptions from "./emailOptions.interface"
 
type EmailAsyncOptions = Pick<ModuleMetadata, "imports"> &
  Pick<FactoryProvider<EmailOptions>, "useFactory" | "inject">
export default EmailAsyncOptions

Please notice that FactoryProvider is generic and we pass EmailOptions to it to enforce the correct configuration.

Once we have the above, we can define our registerAsync method.

email.module.ts#

import { DynamicModule, Module } from "@nestjs/common"
import EmailService from "./email.service"
import { EMAIL_CONFIG_OPTIONS } from "./constants"
import EmailOptions from "./emailOptions.interface"
import EmailAsyncOptions from "./emailAsyncOptions.type"
@Module({})
export class EmailModule {
  static register(options: EmailOptions): DynamicModule {
    return {
      module: EmailModule,
      providers: [
        {
          provide: EMAIL_CONFIG_OPTIONS,
          useValue: options,
        },
        EmailService,
      ],
      exports: [EmailService],
    }
  }
  static registerAsync(options: EmailAsyncOptions): DynamicModule {
    return {
      module: EmailModule,
      imports: options.imports,
      providers: [
        {
          provide: EMAIL_CONFIG_OPTIONS,
          useFactory: options.useFactory,
          inject: options.inject,
        },
        EmailService,
      ],
      exports: [EmailService],
    }
  }
}

Under the hood, our registerAsync method is very similar to register. The difference is that it uses useFactory and inject instead of useValue. It also accepts an array of additional modules to import through options.imports.

Thanks to creating a way to configure the EmailModule asynchronously, we can now use it with various configurations depending on the use case and still use the dependency injection mechanism.

EmailModule.registerAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (configService: ConfigService) => ({
    service: configService.get('NEWSLETTER_EMAIL_SERVICE'),
    user: configService.get('NEWSLETTER_EMAIL_USER'),
    password: configService.get('NEWSLETTER_EMAIL_PASSWORD'),
  }),
}),

Naming conventions#

So far, we’ve only defined the register and registerAsync methods. It is significant to notice that NestJS doesn’t enforce any naming conventions but has some guidelines.

register and registerAsync#

The register and registerAsync methods we’ve used in this article so far are supposed to configure a module for use only with the module that imports it.

To illustrate it, let’s look at the EmailSchedulingModule.

emailScheduling.module.ts#

import { Module } from '@nestjs/common';
import EmailSchedulingService from './emailScheduling.service';
import { EmailModule } from '../email/email.module';
import EmailSchedulingController from './emailScheduling.controller';
import { ConfigModule, ConfigService } from '@nestjs/config';
 
@Module({
  imports: [
    EmailModule.registerAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (configService: ConfigService) =&gt; ({
        service: configService.get('EMAIL_SERVICE'),
        user: configService.get('EMAIL_USER'),
        password: configService.get('EMAIL_PASSWORD'),
      }),
    }),
  ],
  controllers: [EmailSchedulingController],
  providers: [EmailSchedulingService],
})
export class EmailSchedulingModule {}

Above, we provide the configuration for the EmailModule that we only want to use in the EmailSchedulingModule.

forRoot and forRootAsync#

With forRoot and forRootAsync methods, we aim to configure a dynamic module once and reuse this configuration in multiple places. Therefore, it makes a lot of sense with global modules.

A great example is the TypeOrmModule module provided by NestJS.

database.module.ts#

import { Module } from "@nestjs/common"
import { TypeOrmModule } from "@nestjs/typeorm"
import { ConfigModule, ConfigService } from "@nestjs/config"
import Address from "../users/address.entity"
@Module({
  imports: [
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (configService: ConfigService) => ({
        type: "postgres",
        username: configService.get("POSTGRES_USER"),
        password: configService.get("POSTGRES_PASSWORD"),
        entities: [Address],
        autoLoadEntities: true, // ...
      }),
    }),
  ],
})
export class DatabaseModule {}

forFeature and forFeatureAsync#

With the forFeature and forFeatureAsync methods, we can alter the configuration specified using forRootAsync. Again, a good example is the TypeOrmModule.

categories.module.ts#

import { Module } from "@nestjs/common"
import CategoriesController from "./categories.controller"
import CategoriesService from "./categories.service"
import Category from "./category.entity"
import { TypeOrmModule } from "@nestjs/typeorm"
@Module({
  imports: [TypeOrmModule.forFeature([Category])],
  controllers: [CategoriesController],
  providers: [CategoriesService],
})
export class CategoriesModule {}

Above, we specify additional configuration using forFeature() that’s applicable only in the CategoriesModule.

Configurable module builder#

Configuring a dynamic module can be difficult, especially with the asynchronous methods. Fortunately, NestJS has a ConfigurableModuleBuilder class that does much of the work for us. To use it, let’s create a separate file.

email.module-definition.ts#

import { ConfigurableModuleBuilder } from "@nestjs/common"
 
import EmailOptions from "./emailOptions.interface"
 
export const {
  ConfigurableModuleClass: ConfigurableEmailModule,
  MODULE_OPTIONS_TOKEN: EMAIL_CONFIG_OPTIONS,
} = new ConfigurableModuleBuilder<EmailOptions>().build()

Now, we need our EmailModule to extend the ConfigurableEmailModule class.

email.module.ts#

import { Module } from "@nestjs/common"
import { ConfigurableEmailModule } from "./email.module-definition"
import EmailService from "./email.service"
@Module({
  providers: [EmailService],
  exports: [EmailService],
})
export class EmailModule extends ConfigurableEmailModule {}

Thanks to the above, our EmailModule allows us to use both register and registerAsync classes.

For it to work as expected, we need to remember to use the EMAIL_CONFIG_OPTIONS constant that we got from the email.module-definition.ts file.

Extending auto-generated methods#

If we need additional logic, we can extend the auto-generated methods. When doing that, the ConfigurableModuleAsyncOptions can come in handy.

import { ConfigurableModuleAsyncOptions, DynamicModule, Module } from "@nestjs/common"
import { ConfigurableEmailModule } from "./email.module-definition"
import EmailService from "./email.service"
import EmailOptions from "./emailOptions.interface"
@Module({
  providers: [EmailService],
  exports: [EmailService],
})
export class EmailModule extends ConfigurableEmailModule {
  static register(options: EmailOptions): DynamicModule {
    return {
      // you can put additional configuration here
      ...super.register(options),
    }
  }
  static registerAsync(options: ConfigurableModuleAsyncOptions<EmailOptions>): DynamicModule {
    return {
      // you can put additional configuration here
      ...super.registerAsync(options),
    }
  }
}

Using methods other than register and registerAsync#

If we want to use methods other than register and registerAsync, we need to call the setClassMethodName function.

email.module-definition.ts#

import { ConfigurableModuleBuilder } from "@nestjs/common"
 
import EmailOptions from "./emailOptions.interface"
 
export const {
  ConfigurableModuleClass: ConfigurableEmailModule,
  MODULE_OPTIONS_TOKEN: EMAIL_CONFIG_OPTIONS,
} = new ConfigurableModuleBuilder<EmailOptions>().setClassMethodName("forRoot").build()

Summary#

In this article, we’ve gone through the idea of dynamic modules. To illustrate it, we implemented it manually and learned how it works under the hood. Then, we’ve learned how to use utilities built into NestJS that can simplify this process significantly. Dynamic modules are a handy feature that allows us to make our modules customizable while taking advantage of the dependency injection mechanism.