Modules

Introduction

Every NestJS application is a tree of modules. The root module (AppModule) sits at the top, and each feature of your app — users, products, orders, authentication — lives in its own module underneath. Understanding modules is the key to understanding how Nest finds and connects everything else.

What is a Module?

A module is a class annotated with @Module() that groups a closely related set of capabilities. Think of it like a department in a company: the "Users" department has its own staff (providers) and its own front desk (controllers), and it can choose which staff it lends to other departments.

Nest uses the module tree to build its dependency injection container. When a controller asks for a service, Nest only looks inside that controller's own module and the modules it imports — this boundary is what keeps large applications organized.

The @Module() Decorator

Creating a Feature Module

nest g module users
nest g controller users
nest g service users

// src/users/users.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller.js';
import { UsersService } from './users.service.js';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

The CLI also adds UsersModule to the imports array of AppModule automatically. That one import is what connects the whole users feature to your application:

// src/app.module.ts
import { Module } from '@nestjs/common';
import { UsersModule } from './users/users.module.js';

@Module({
  imports: [UsersModule],
})
export class AppModule {}

Sharing Providers with Exports

Suppose an OrdersService needs to look up users. Instead of creating a second UsersService, UsersModule exports its service, and OrdersModule imports UsersModule:

// src/users/users.module.ts
@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService], // now other modules may use it
})
export class UsersModule {}

// src/orders/orders.module.ts
@Module({
  imports: [UsersModule], // brings in UsersService
  controllers: [OrdersController],
  providers: [OrdersService],
})
export class OrdersModule {}

// src/orders/orders.service.ts
@Injectable()
export class OrdersService {
  constructor(private readonly usersService: UsersService) {}
}

Providers are singletons by default, so OrdersModule receives the exact same UsersService instance that UsersModule uses — modules share one instance rather than each creating their own.

Global Modules

Some providers — configuration, logging, a database connection — are needed almost everywhere. Importing their module into every feature module gets repetitive, so Nest lets you mark a module as global with @Global():

import { Global, Module } from '@nestjs/common';
import { LoggerService } from './logger.service.js';

@Global()
@Module({
  providers: [LoggerService],
  exports: [LoggerService],
})
export class LoggerModule {}

Register a global module once (usually in AppModule) and its exported providers become injectable everywhere without further imports.

Dynamic Modules

A dynamic module is configured at import time by calling a static method, conventionally named forRoot() (configure once for the whole app) or forFeature() (configure per feature module). You will use many of these from official packages:

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),   // lesson 11
    TypeOrmModule.forRoot({ /* db options */ }), // lesson 12
    UsersModule,
  ],
})
export class AppModule {}

You rarely need to write your own dynamic module as a beginner, but recognizing the forRoot()/forFeature() pattern makes the official packages much easier to understand.

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

You learned how modules organize a Nest app into features, how imports and exports share providers safely, and when global and dynamic modules are useful. Next, you will build the entry points of your API — controllers and routing.