Shared modules in NestJS - Deep Dive

Overview - Shared modules

What is it?

In NestJS, shared modules are special modules designed to provide common services, components, or providers that can be used across multiple other modules in an application. Instead of duplicating code or creating multiple instances of the same service, shared modules allow you to centralize and reuse functionality easily. They help organize code and manage dependencies efficiently in larger applications.

Why it matters

Without shared modules, developers would have to duplicate services or components in every module that needs them, leading to inconsistent behavior, harder maintenance, and wasted resources. Shared modules solve this by enabling a single source of truth for common features, making the app more scalable and easier to update. This means faster development and fewer bugs in real projects.

Where it fits

Before learning shared modules, you should understand basic NestJS modules, providers, and dependency injection. After mastering shared modules, you can explore advanced module patterns like dynamic modules, global modules, and module refactoring techniques.

Mental Model

Core Idea

A shared module is a reusable container that exports common services or components so multiple modules can use the same instance without duplication.

Think of it like...

Imagine a shared toolbox in a workshop that everyone can access. Instead of each worker buying their own hammer or screwdriver, they all use tools from the same box, saving money and space.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Module A      │       │ Shared Module │       │ Module B      │
│               │◄──────│  (exports)   │──────►│               │
│ (imports)     │       │  Service X   │       │ (imports)     │
└───────────────┘       └───────────────┘       └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding NestJS Modules

Concept: Learn what a module is in NestJS and how it organizes code.

A NestJS module is a class annotated with @Module decorator. It groups related controllers and providers (services) together. Modules help organize the app into logical units. Each module can import other modules to use their exported providers.

Result

You can create a simple module that holds services and controllers, organizing your app cleanly.

Understanding modules is essential because shared modules are just special modules designed for reuse.

2

Foundation

Providers and Dependency Injection Basics

Concept: Learn how services (providers) are created and injected in NestJS.

Providers are classes that can be injected into constructors of other classes. NestJS uses dependency injection to create and share instances of providers automatically. This allows loose coupling and easier testing.

Result

You can create a service and inject it into a controller or another service.

Knowing how providers work is key to understanding how shared modules share the same service instance.

3

Intermediate

Creating a Shared Module

🤔Before reading on: do you think a shared module should export its providers or just declare them? Commit to your answer.

Concept: Learn how to create a module that exports providers for reuse.

To create a shared module, define a module with providers and export those providers using the 'exports' array in @Module. Other modules can then import this shared module to use the exported providers.

Result

Multiple modules can import the shared module and use the same service instance.

Exporting providers is what makes a module shared; without exports, other modules cannot access those providers.

4

Intermediate

Importing Shared Modules in Other Modules

🤔Before reading on: if two modules import the same shared module, do they get separate instances of the service or the same one? Commit to your answer.

Concept: Learn how importing a shared module works and how instances are shared.

When multiple modules import a shared module, NestJS creates a single instance of each exported provider per application context. This means all modules share the same service instance, avoiding duplication.

Result

Shared services behave like singletons across modules that import the shared module.

Understanding this sharing behavior prevents bugs related to multiple instances and inconsistent state.

5

Intermediate

Avoiding Circular Dependencies with Shared Modules

Concept: Learn how to structure shared modules to prevent circular imports.

Circular dependencies happen when two modules import each other directly or indirectly. To avoid this, keep shared modules focused on common services only and avoid importing modules that depend on them. Use forwardRef() if necessary to break cycles.

Result

Your app compiles and runs without dependency errors.

Knowing how to avoid circular dependencies keeps your module graph clean and your app stable.

6

Advanced

Global Shared Modules for App-wide Providers

🤔Before reading on: do you think marking a shared module as global means you must import it everywhere? Commit to your answer.

Concept: Learn how to make a shared module global so its providers are available everywhere without importing.

By adding 'global: true' in the @Module decorator, a shared module becomes global. Its exported providers are automatically available in all modules without explicit import. This is useful for truly common services like logging or config.

Result

You can use shared services anywhere without importing the module repeatedly.

Global modules simplify usage but should be used sparingly to avoid hidden dependencies.

7

Expert

Dynamic Shared Modules with Configurable Providers

🤔Before reading on: do you think shared modules can accept parameters to customize their providers? Commit to your answer.

Concept: Learn how to create shared modules that accept configuration and provide customized services.

Dynamic modules use a static method returning a module definition with providers configured based on input parameters. This allows shared modules to be flexible and reusable with different settings in different parts of the app.

Result

You can create a shared module that adapts its behavior per usage context.

Understanding dynamic shared modules unlocks advanced patterns for scalable and configurable NestJS apps.

Under the Hood

NestJS uses a dependency injection container that keeps track of providers and their scopes. When a shared module exports providers, the container registers them once. When other modules import the shared module, they receive references to the same provider instances from the container, ensuring singleton behavior within the app context.

Why designed this way?

This design avoids duplication of services and promotes code reuse. It also aligns with the modular architecture principle, making apps easier to maintain and scale. Alternatives like duplicating services per module would waste memory and cause inconsistent states.

┌─────────────────────────────┐
│ Dependency Injection Container│
│                             │
│  ┌───────────────┐          │
│  │ Shared Module │          │
│  │  Providers    │◄─────────┤
│  └───────────────┘          │
│       ▲                     │
│       │                     │
│  ┌───────────────┐          │
│  │ Module A      │          │
│  └───────────────┘          │
│       ▲                     │
│  ┌───────────────┐          │
│  │ Module B      │          │
│  └───────────────┘          │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: If two modules import the same shared module, do they get separate service instances? Commit to yes or no.

Common Belief: Each module that imports a shared module gets its own separate instance of the shared services.

Reality: All modules importing the shared module share the same instance of its exported providers within the application context.

Why it matters: Believing otherwise can lead to unnecessary debugging when state changes in one module don't reflect in another, causing confusion and bugs.

Quick: Does marking a module as global mean you must still import it everywhere? Commit to yes or no.

Common Belief: Even if a module is global, you still need to import it in every module that uses its providers.

Reality: Global modules automatically provide their exported providers to all modules without needing explicit imports.

Why it matters: Not knowing this leads to redundant imports and bloated code, reducing the benefits of global modules.

Quick: Can shared modules contain controllers that are reused across modules? Commit to yes or no.

Common Belief: Shared modules can export controllers to be reused in other modules.

Reality: Controllers are not exported by modules; only providers can be exported and shared. Controllers belong to their own module.

Why it matters: Trying to share controllers via shared modules leads to architectural confusion and runtime errors.

Quick: Is it safe to import a shared module everywhere without considering circular dependencies? Commit to yes or no.

Common Belief: You can import shared modules anywhere without worrying about circular dependencies.

Reality: Improper imports of shared modules can cause circular dependencies, breaking the app.

Why it matters: Ignoring this can cause runtime errors and difficult-to-debug issues in large apps.

Expert Zone

1

Shared modules export providers but do not re-export imported modules automatically; you must explicitly export what you want to share.

2

Global shared modules can cause hidden dependencies, making testing and refactoring harder if overused.

3

Dynamic shared modules can cache configuration to optimize performance but require careful design to avoid stale data.

When NOT to use

Avoid using shared modules when the service or provider is only relevant to a single module or has state that should not be shared. Instead, define providers locally. For cross-cutting concerns, consider middleware or interceptors. For very dynamic or context-specific services, use request-scoped providers.

Production Patterns

In production, shared modules often provide logging, configuration, database connections, or utility services. They are carefully designed as global or imported modules depending on usage. Dynamic shared modules enable multi-tenant apps by configuring services per tenant. Circular dependency checks and module boundaries are strictly enforced.

Connections

Dependency Injection

Shared modules build on dependency injection by providing reusable providers that the DI container manages.

Understanding dependency injection helps grasp how shared modules share single instances and manage lifecycles.

Microservices Architecture

Shared modules relate to microservices by encapsulating reusable logic that can be shared across service boundaries or within services.

Knowing shared modules aids in designing modular microservices with clear boundaries and shared utilities.

Library Packaging in Software Engineering

Shared modules are similar to libraries or packages that bundle reusable code for multiple projects or modules.

Recognizing this connection helps understand the importance of modular design and code reuse beyond NestJS.

Common Pitfalls

#1 Creating a shared module but forgetting to export providers.

Wrong approach:

@Module({
providers: [CommonService],
imports: []
})
export class SharedModule {}

Correct approach:

@Module({
providers: [CommonService],
exports: [CommonService],
imports: []
})
export class SharedModule {}

Root cause:

Not exporting providers means other modules cannot access them, defeating the purpose of sharing.

#2 Importing a shared module multiple times without understanding singleton scope.

Wrong approach:

import { SharedModule } from './shared.module';

@Module({
imports: [SharedModule, SharedModule],
})
export class SomeModule {}

Correct approach:

import { SharedModule } from './shared.module';

@Module({
imports: [SharedModule],
})
export class SomeModule {}

Root cause:

Importing the same module multiple times is redundant and can confuse the DI container.

#3 Marking a shared module as global but still importing it everywhere.

Wrong approach:

@Global()
@Module({
providers: [ConfigService],
exports: [ConfigService],
})
export class SharedModule {}

@Module({
imports: [SharedModule],
})
export class FeatureModule {}

Correct approach:

@Global()
@Module({
providers: [ConfigService],
exports: [ConfigService],
})
export class SharedModule {}

@Module({
imports: [], // no need to import SharedModule
})
export class FeatureModule {}

Root cause:

Global modules automatically provide their exports app-wide; importing them again is unnecessary.

Key Takeaways

Shared modules in NestJS centralize common providers to be reused across multiple modules, avoiding duplication.

Exporting providers in a shared module is essential for other modules to access them.

Multiple modules importing the same shared module share the same provider instances, ensuring singleton behavior.

Global shared modules make providers available app-wide without explicit imports but should be used carefully.

Dynamic shared modules allow configuration-based customization, enabling flexible and scalable applications.