Suggest an edit

Improve this article

Refine the answer for “What does the IoC container do in NestJS?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## What the IoC container is in NestJS

The **IoC container (Inversion of Control Container)** in NestJS is the **mechanism that manages creating, storing, and injecting dependencies** (providers) in the application.
It implements the **Inversion of Control** principle:
→ you **don't create objects by hand**, you **hand that off to the framework**.

## In simple terms

Without an IoC container, you'd write:

```javascript
const usersService = new UsersService();
const usersController = new UsersController(usersService);
```

With the IoC container, Nest does this **automatically**:
you just declare the dependencies in the constructor:

```javascript
@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}
}
```

Nest itself:

1. creates a `UsersService` instance;
2. stores it in the DI container;
3. injects it into `UsersController`.

## How the IoC container works, step by step

1. It **scans the modules** (`@Module()`) and collects the list of all `providers`, `controllers`, and `imports`.
2. It **registers providers** in the container (by token, usually the class itself or a string identifier).
3. It **creates provider instances** (a single shared instance, a Singleton, by default).
4. It **tracks dependencies** and injects them when other classes are created.
5. It **holds references** to already-created instances, to reuse them for later requests.

## A visual example

```javascript
@Injectable()
export class UsersService {
  findAll() {
    return ['John', 'Alex'];
  }
}

@Controller('users')
export class UsersController {
  constructor(private usersService: UsersService) {}

@Get()
  getUsers() {
    return this.usersService.findAll();
  }
}

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

What the IoC container does:

1. Sees `UsersModule`.
2. Registers `UsersService` as a provider.
3. Creates a `UsersService` instance and stores it.
4. When creating `UsersController`, sees that its constructor needs `UsersService`.
5. Injects the ready-made instance.

## The key idea, **inversion of control**

Normally:

> You create dependencies by hand.

With IoC:

> You just declare what you need, **the container decides how to create it**.

## Advantages of the IoC container in NestJS

| Advantage | Explanation |
|---|---|
| Reduced coupling | Classes don't depend directly on how their dependencies are implemented. |
| Reuse | One provider instance can be used in many places. |
| Easy testing | Dependencies can be swapped with mocks. |
| Automatic lifecycle management | Nest creates, caches, and destroys instances itself. |
| Flexibility | Providers can be overridden (`useClass`, `useValue`, `useFactory`). |

## Internal details (if you're curious)

- Every module has **its own IoC container** (its own scope).
- Containers can **inherit dependencies** from imported modules.
- When looking up a dependency, Nest walks "up the module tree" until it finds the needed provider.

## An example with tokens and factories

```javascript
@Module({
  providers: [
    {
      provide: 'RANDOM',
      useFactory: () => Math.random(),
    },
  ],
})
export class AppModule {}

@Injectable()
export class ExampleService {
  constructor(@Inject('RANDOM') private random: number) {}

log() {
    console.log(this.random);
  }
}
```

The IoC container:

- registers `'RANDOM'` as a token;
- calls the `useFactory` factory;
- stores the result;
- injects the `random` value when `ExampleService` is created.

## A visual diagram of how IoC works

```javascript
┌────────────────────┐
│ @Module()          │
│ imports, providers │
└───────┬────────────┘
        │
        ▼
┌──────────────────────────┐
│ NestJS's IoC container   │
│ - Registers providers    │
│ - Creates instances      │
│ - Manages dependencies   │
└───────────┬──────────────┘
            │
            ▼
┌────────────────────────┐
│ Controller / Service    │
│ → receives dependencies │
│   through the constructor│
└────────────────────────┘
```

## Summary

| Term | Explanation |
|---|---|
| IoC container | The system that manages dependencies (Dependency Injection) |
| Job | Creating, storing, and injecting providers |
| Principle | Inversion of control: an object doesn't create its own dependencies |
| Advantages | Reduced coupling, reuse, testability |

Markdown · drag & drop images · ⌘B / ⌘I shortcuts613 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.