O que são módulos no NestJS?

Question

Accepted Answer

Um **módulo** é uma classe decorada com `@Module()` que **agrupa componentes relacionados** — controllers, providers/services — em uma unidade coesiva. Módulos são como o NestJS organiza uma aplicação em funcionalidades, e toda aplicação Nest possui pelo menos um `AppModule` raiz.

## Definindo um módulo

```ts
import { Module } from "@nestjs/common";

@Module({
  controllers: [UsersController],    // controllers belonging to this module
  providers: [UsersService],          // providers (services) this module creates
  imports: [DatabaseModule],          // OTHER modules whose exports this module needs
  exports: [UsersService],            // what this module makes available to importers
})
export class UsersModule {}
```

## As quatro propriedades principais

```text
controllers → the controllers (request handlers) in this module
providers   → the providers/services defined and instantiated here (for DI)
imports     → other modules whose EXPORTED providers this module can use
exports     → the subset of THIS module's providers shared with importing modules
```

Módulos formam um **escopo de DI**: um provider está disponível dentro de seu módulo, e para outros módulos apenas se **exportado** (e o outro módulo o **importa**).

## O módulo raiz

```ts
@Module({
  imports: [UsersModule, AuthModule, DatabaseModule],   // compose feature modules
})
export class AppModule {}   // the root — bootstrapped to start the app
```

Toda aplicação possui um `AppModule` raiz que importa os módulos de funcionalidades, compondo a aplicação inteira.

## Organização baseada em funcionalidades

```text
src/
  app.module.ts            (root — imports feature modules)
  users/
    users.module.ts        (groups users controller + service)
    users.controller.ts
    users.service.ts
  auth/
    auth.module.ts
  database/
    database.module.ts     (shared infrastructure)
```

A convenção é **um módulo por funcionalidade/domínio** (users, auth, products), mantendo código relacionado junto e dependências explícitas.

## Compartilhando providers entre módulos

```ts
// UsersModule exports UsersService...
@Module({ providers: [UsersService], exports: [UsersService] })
export class UsersModule {}

// ...so AuthModule can use it by importing UsersModule
@Module({ imports: [UsersModule] })   // now AuthModule can inject UsersService
export class AuthModule {}
```

Para usar um provider de outro módulo, o módulo que fornece deve **exportá-lo** e o módulo consumidor deve **importar** o módulo fornecedor — tornando as dependências explícitas.

## Por que isso importa

Módulos são a espinha dorsal organizacional de toda aplicação NestJS — eles agrupam controllers e providers relacionados em unidades de funcionalidades coesivas e definem os limites de injeção de dependência.

Entender as quatro propriedades (`controllers`, `providers`, `imports`, `exports`) e especialmente o mecanismo de **import/export** para compartilhar providers entre módulos é essencial: é assim que o NestJS alcança uma arquitetura modular e fracamente acoplada, onde cada funcionalidade é auto-contida e as dependências são explícitas.

A estrutura de módulo baseada em funcionalidades (um módulo por domínio) é a forma padrão de organizar aplicações Nest para escalabilidade e manutenibilidade.

Módulos, juntamente com controllers e providers, formam a arquitetura central do NestJS, tornando-os conhecimento fundamental — dominar como estruturar uma aplicação em módulos e conectar providers entre eles via imports/exports é necessário para construir qualquer aplicação NestJS não trivial e é um ponto frequente de confusão que vale a pena entender bem desde o início.