Context

I recently started working with NestJS and wanted to deepen my understanding of its module system, particularly how providers are defined, registered, and injected within modules. I aimed to clarify the concepts of modules, providers, and the dependency injection mechanism in NestJS.

NestJS applications are built upon a powerful, modular architecture, and modules serve as the fundamental organizational unit for grouping related code components, particularly providers.

NestJS Modules

A NestJS module is an internal structure annotated with the @Module() decorator that helps organize the code and define module boundaries. They function primarily as configuration files that define the application’s structure by connecting controllers, services, and other components, acting as the wiring instructions for the Dependency Injection (DI) system. They can also control what’s available for other modules to use.

The @Module() decorator is used to define everything about a module, and a module typically includes a set of properties:

• providers: Classes that can be injected as dependencies (services, factories, repositories);
• controllers: Classes responsible for handling incoming requests and returning responses;
• imports: Other modules required by this module;
• exports: A subset of providers available for use by other modules that import this module.

How providers work inside modules

Providers are essential for empowering application logic and include components like services, repositories, factories, and helpers. The core concept is that a provider can be injected as a dependency.

Defining and registering providers

Classes that contain business logic (like Services or Commands/Queries) are annotated with the @Injectable() decorator, which signals to Nest’s Dependency Injection system that they can be managed and injected.

For a provider to be usable, it must be registered by adding it to the providers array of a module:

import { Module } from '@nestjs/common';
import { AuthService } from './auth.service';
import { LocalStrategy, JwtStrategy } from './auth-module/strategies';

@Module({
  providers: [AuthService, LocalStrategy, JwtStrategy],
  // ...
})
export class AuthModule {}

Or:

import { Module } from '@nestjs/common';
import { UserService } from './user.service';

@Module({
  providers: [UserService], // registering UserService as a provider
  imports: [],
  controllers: [],
  exports: [],
})
export class UserModule {}

The dependency injection mechanism

The module system enables Nest’s runtime to resolve the dependency injection graph, coordinating the instantiation and provision of objects.

• Injection Token: When a provider is registered, Nest uses a provider token to uniquely identify it. In the common shorthand syntax (e.g., providers: [AuthService]), the class name acts as both the token and the instruction for instantiation.
• Constructor Injection: Consumers, such as controllers or other services, request a provider by defining it in their constructor. Nest looks up the required type (token) and injects the correct instance.

Custom providers and instantiation methods

Nest’s DI system provides flexibility through custom providers, which allow developers to define how an instance should be created and what value or class should be used. These definitions use an object literal format inside the providers array containing a unique provide token and one of the instantiation strategies:

When a custom provider uses a string or symbol as its token (e.g., export const TOKEN_NAME = OKTA_CLIENT), the consuming class must use the @Inject(TOKEN_NAME) decorator to explicitly declare which provider is being requested in the constructor.

Provider scopes

The scope of a provider determines how often an instance of that class is created.

• Default Scope (Singleton): By default, providers are singletons, meaning a single instance is created and shared across the entire application once the module is built.
  • That’s the recommended best practice for the vast majority of services, especially those that are thread-safe or manage shared, application-wide resources.
  • Use cases:
    • Stateless services/business logic:
      • Core business logic services, abstract functions, utility helpers that are stateless.
    • Configuration objects:
      • Objects that store static, system-wide config data.
    • Application-wide resources:
      • Services that manage a single, shared resource across the application, such as global logging utilities, HTTP clients (to avoid unnecessary connections), or connections pools.
    • Factory patterns:
      • An implementation of a factory pattern, which creates instances of other classes, can be a Singleton to save memory if its own implementation is thread-safe.
• Request Scope: A new instance of the provider is created every time the provider is injected. The instance is shared only within the lifecycle of that specific request.
  • Use cases:
    • Request Context and Traceability:
      • Essential for architectural patterns that require maintaining request-specific state, such as tracking a unique correlation ID for logging and distributed tracing across multiple services within a single request context.
    • Transactional Boundaries/Unit of Work:
      • Database connection objects are often scoped, as they must be short-lived and shared only across operations within the same transaction or unit of work related to a single HTTP request. This prevents parallel requests from affecting the state of others.
  • Performance Note on Request Scope: Adopting Request scoping introduces a definite performance penalty due to the recurrent instantiation and cleanup for every request. Because of the transitive nature (scope contamination), developers must rigorously isolate and minimize the boundary of Request-scoped dependencies to prevent severe performance degradation.
• Transient Scope: A new, distinct instance is created every time the provider is injected into any consuming component. Injecting a Transient provider into a Singleton consumer will give the consumer a fresh instance, but the consumer itself remains Singleton.
  • Use cases:
    • Stateful Utilities/Builders
      • Services or utilities that maintain mutable internal state and require a clean, independent instance for each operation. Examples include factory classes or complex object builders where you want to ensure one consumer’s usage does not interfere with another’s.
    • Non-Thread-Safe Objects:
      • Services that read or write data from a file or contain instance-level state that is not thread safe. Since a new instance is created every time, thread-safety is less of a concern.

Nest’s module system and provider registration collectively operate like a highly organized backstage crew preparing a concert: the module configuration (@Module()) acts as the detailed production schedule, declaring who the performers (providers) are and where they belong. The Dependency Injection system (the conductor) ensures that whenever one performer (a controller) needs a tool (a service/provider), the right instance of that tool is immediately and seamlessly available, whether it’s the custom-built version for a special task or the standard default version.