Chapter 05 — Modules (Organizing the App)
Chapter 05 — Modules (Organizing the App)
Hey everyone! Welcome back to Namaste NestJS! 🙏
We've met the receptionist (controller) and the chef (provider). Today we build the building that houses them — the Module. Modules are how Nest keeps a growing app from turning into a mess. This chapter completes your Season 1 foundation, and after it you'll understand the shape of every Nest app you ever open.
What we will cover:
- What a module is and why every app needs them
- The four keys of
@Module: imports, controllers, providers, exports - The root module and feature modules
- Sharing providers between modules (exports + imports)
- Shared modules and global modules
- Dynamic modules (
forRoot/forFeature) - How Nest builds the module graph at startup
- Common mistakes
- Interview Questions
1. What is a Module?
A module is a class with a @Module() decorator that groups related controllers and providers into one cohesive feature.
┌─────────────────────────────────────────────────────────────┐ │ WHAT IS A MODULE? │ ├─────────────────────────────────────────────────────────────┤ │ │ │ A MODULE is a box around ONE feature. │ │ │ │ ┌── CatsModule ──────────────┐ │ │ │ CatsController (routes) │ │ │ │ CatsService (logic) │ │ │ └────────────────────────────┘ │ │ │ │ Everything about "cats" lives in one box. Tidy. 📦 │ │ │ └─────────────────────────────────────────────────────────────┘
A simple analogy: a company has departments — Sales, HR, Engineering. Each has its own people and responsibilities, but they can request help from each other. A module is a department. The company itself is the root module.
2. The Four Keys of @Module
The @Module() decorator takes an object with (up to) four properties. Learn these four and modules hold no more secrets.
@Module({
imports: [], // other MODULES this module needs
controllers: [], // route handlers this module OWNS
providers: [], // injectable logic this module OWNS
exports: [], // providers this module SHARES with importers
})
export class CatsModule {}
| Key | Meaning | Think of it as |
|---|---|---|
imports | Other modules whose exports I want to use | "Who do I borrow from?" |
controllers | The routes this module defines | "My reception desks" |
providers | The services/logic this module creates | "My staff" |
exports | Which of my providers others may use | "Who I lend out" |
3. Root Module vs Feature Modules
Every app has exactly one root module (AppModule) — the entry point Nest is given in main.ts. Everything else is a feature module that the root imports.
┌── AppModule (ROOT) ──┐
│ imports: [ │
│ CatsModule, │
│ UsersModule, │
│ OrdersModule, │
│ ] │
└──────────┬───────────┘
│ imports…
┌────────────────┼────────────────┐
▼ ▼ ▼
CatsModule UsersModule OrdersModule
(feature) (feature) (feature)
In simple words: you don't cram everything into AppModule. You create a module per feature (nest g resource cats does this for you) and the root module just imports them all. This keeps each feature independent and testable.
4. Sharing a Provider Between Modules
Here's the rule that trips up every beginner:
┌─────────────────────────────────────────────────────────────┐ │ THE GOLDEN RULE OF MODULE SHARING │ │ │ │ Providers are PRIVATE to their module by default. │ │ │ │ To use CatsService in another module you must: │ │ 1. EXPORT it from CatsModule │ │ 2. IMPORT CatsModule where you need it │ │ │ └─────────────────────────────────────────────────────────────┘
Say OrdersModule needs CatsService. Two steps:
// Step 1 — CatsModule EXPORTS the service it wants to share
@Module({
controllers: [CatsController],
providers: [CatsService],
exports: [CatsService], // 👈 "others may use CatsService"
})
export class CatsModule {}
// Step 2 — OrdersModule IMPORTS CatsModule
@Module({
imports: [CatsModule], // 👈 now OrdersService can inject CatsService
providers: [OrdersService],
})
export class OrdersModule {}
Now trace what happens when you inject it:
HAND TRACE: OrdersService needs CatsService
──────────────────────────────────────────────
1. OrdersService constructor asks for CatsService
2. Nest looks in OrdersModule's own providers → not there
3. Nest checks OrdersModule's IMPORTS → finds CatsModule
4. Does CatsModule EXPORT CatsService? ✅ yes
5. Injects the SAME shared CatsService singleton
▼
Wired successfully ✔
(If step 4 were "no", you'd get: "Nest can't resolve dependencies")
Important: importing a module does not automatically give you all its providers — only the ones it explicitly exports. Private by default, shared on purpose.
5. Shared Modules & Global Modules
Some providers are needed everywhere — a database connection, a logger, a config service. Two patterns handle this.
(a) Shared module — a normal module you import wherever needed. Because Nest providers are singletons, importing the same module in ten places still gives everyone the same instance.
(b) Global module — mark it @Global() and its exports are available app-wide without importing it every time.
import { Module, Global } from '@nestjs/common';
@Global() // 👈 makes exports available everywhere
@Module({
providers: [DatabaseService],
exports: [DatabaseService],
})
export class DatabaseModule {}
Pro tip: use @Global() sparingly. It's convenient for truly cross-cutting things (config, DB), but overusing it hides dependencies and makes the app harder to reason about. Explicit imports are usually healthier.
6. Dynamic Modules — forRoot & forFeature
You've probably seen ConfigModule.forRoot() or TypeOrmModule.forRoot({...}). Those are dynamic modules — modules configured with arguments at import time.
// a static import (no config):
imports: [CatsModule]
// a DYNAMIC import (pass configuration in):
imports: [
ConfigModule.forRoot({ isGlobal: true }),
TypeOrmModule.forRoot({ type: 'postgres', host: 'localhost' }),
]
NAMING CONVENTION (you'll see this everywhere): ──────────────────────────────────────────────── forRoot() → configure a module ONCE, globally (the connection) forFeature() → register a slice for one feature (e.g. specific entities)
Q: Why do libraries need dynamic modules?
A: Because a reusable module (like a database or config module) can't hard-code your settings. forRoot() lets you pass the connection details, and the module returns a fully configured version of itself. You'll build one yourself in a later chapter.
7. How Nest Builds the Module Graph
At startup, Nest walks your modules like a tree and assembles everything in order.
STARTUP TRACE:
──────────────
1. Nest is handed AppModule (in main.ts)
2. It reads AppModule's imports → [CatsModule, UsersModule, ...]
3. For EACH imported module (recursively):
• instantiate its providers (singletons)
• register its exports so importers can see them
• register its controllers' routes
4. Resolve all constructor dependencies via the DI container
5. Everything wired → app.listen() starts the server
▼
A fully connected object graph, ready to serve requests ✔
In simple words: modules are the map Nest follows to discover and connect your entire app. Controllers and providers are the destinations; modules are the roads between them.
8. Little Traps Beginners Fall Into
┌─────────────────────────────────────────────────────────────┐ │ COMMON MISTAKES ❌ │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Importing a module but expecting ALL its providers. │ │ → You only get what it EXPORTS. │ │ │ │ Forgetting to import the feature module into AppModule. │ │ → Its routes simply don't exist. No error, no route. │ │ │ │ Listing a provider in TWO modules' providers: []. │ │ → You get TWO separate instances, not a shared one. │ │ Export from one, import that module instead. │ │ │ │ Overusing @Global() → hidden, hard-to-trace dependencies. │ │ │ └─────────────────────────────────────────────────────────────┘
Interview Questions — Quick Fire!
Q: What is a module in NestJS?
"A module is a class annotated with @Module that groups related controllers and providers into a cohesive feature unit. Every Nest app has at least one root module, and larger apps are organized into feature modules. Modules define the boundaries and the dependency graph of the application."
Q: What are the four properties of the @Module decorator?
"imports lists other modules whose exported providers this module needs; controllers lists the route handlers this module owns; providers lists the injectable services it owns; and exports lists which of its providers are made available to modules that import it."
Q: How do you share a service between two modules?
"Providers are private to their module by default. To share one, you add it to the exports array of the module that owns it, then import that module wherever you need the service. Because providers are singletons, every importer receives the same shared instance."
Q: What is a global module and when should you use it?
"A module marked with @Global makes its exported providers available application-wide without needing to be imported everywhere. It's handy for cross-cutting concerns like configuration, logging, or a database connection, but it should be used sparingly because it hides dependencies and makes the app harder to reason about."
Q: What is a dynamic module and what do forRoot and forFeature mean?
"A dynamic module is one that's configured with arguments at import time, returning a customized version of itself. By convention forRoot configures the module once globally — for example a database connection — while forFeature registers a feature-specific slice, like particular entities or repositories for one module."
Key Points to Remember
| Concept | Key Takeaway |
|---|---|
| Module | A box grouping one feature's controllers + providers. |
| 4 keys | imports · controllers · providers · exports. |
| Root vs feature | One AppModule imports many feature modules. |
| Sharing | Export from owner + import that module. Private by default. |
| @Global() | App-wide exports; use sparingly. |
| Dynamic module | forRoot/forFeature configure a module at import time. |
What's Next?
🎉 That's Season 1 done — you now understand Controllers, Providers/DI, and Modules, the three pillars every Nest app stands on. In Season 2 we follow a request on its full journey through the request pipeline. First stop, Chapter 06: DTOs & Validation — how to describe incoming data with a class and reject bad payloads automatically, so garbage never reaches your logic.
Keep coding, keep shipping! See you in the next one!
Post a Comment