---
id: 49
type: docs
title: "NestJS Feature Module Runbook"
slug: "nestjs-feature-module-runbook"
canonical_url: "https://docs.phatysd.me/content/nestjs-feature-module-runbook"
status: published
revision: 1
published_at: "2026-09-19T17:51:06.174Z"
updated_at: "2026-09-19T17:51:06.174Z"
hierarchy_path: "NestJS > Architecture > Feature Modules"
topics:
  - "NestJS"
  - "TypeScript"
  - "Modules"
  - "Validation"
tags:
  - "nestjs"
  - "typescript"
  - "modules"
  - "validation"
  - "configuration"
related:
  - slug: "nestjs-modules-are-the-boundary"
    title: "NestJS Modules Are the Boundary"
    type: blog
    canonical_url: "https://docs.phatysd.me/content/nestjs-modules-are-the-boundary"
---

# NestJS Feature Module Runbook

NestJS gives a service a strong application structure through modules,
controllers, and providers. Use that structure to make ownership visible:
controllers translate transport input, providers implement use cases, and
modules define the feature boundary.

## Build one feature at a time

A feature module should own the controllers and providers needed for one
business capability:

```ts
@Module({
  imports: [DatabaseModule],
  controllers: [OrdersController],
  providers: [OrdersService, OrdersRepository],
  exports: [OrdersService],
})
export class OrdersModule {}
```

Import the feature module from the root module. Avoid putting every provider in
`AppModule`; the root module should primarily compose the application.

## Keep controllers thin

Controllers should own route decorators, request parameters, DTO boundaries,
and response status decisions. Providers should own business rules and
orchestration. This separation lets unit tests exercise the use case without
booting the whole HTTP application.

```ts
@Controller("orders")
export class OrdersController {
  constructor(private readonly orders: OrdersService) {}

  @Post()
  create(@Body() input: CreateOrderDto) {
    return this.orders.create(input);
  }
}
```

## Validate at the application boundary

Use DTOs and a global `ValidationPipe` for a consistent request contract. A
typical production policy enables transformation only when the DTO and
application semantics expect it, whitelists known properties, and rejects
unexpected input rather than silently accepting a larger payload.

```ts
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
  }),
);
```

Validation is not authorization. A DTO can prove that a field is shaped
correctly; a provider or guard still needs to decide whether the caller may
perform the operation.

## Keep configuration explicit

Load configuration once, validate required environment variables, and inject
configuration through the Nest application rather than reading `process.env`
throughout feature code. Separate safe defaults from values that must be
present in production, such as database URLs, signing keys, and external API
credentials.

Never include secrets in configuration logs or error responses.

## Plan lifecycle and API exposure

Enable shutdown hooks when providers need to close database pools, queues, or
other resources. Test that SIGTERM drains the application within the platform
deadline. If Swagger is enabled, decide whether its UI and raw definitions
should be public in production; API documentation exposure is an operational
choice, not an automatic requirement.

## Production checklist

- Every feature has a module with explicit imports, controllers, providers, and exports.
- Controllers contain transport concerns; providers contain use cases.
- DTO validation is enabled at the application boundary.
- Unknown properties and malformed payloads have a deliberate policy.
- Guards and service-level authorization protect sensitive actions.
- Required configuration is validated before the server accepts traffic.
- Shutdown hooks close external resources and are exercised with SIGTERM.
- Swagger exposure matches the production security policy.

## References

- [NestJS modules](https://docs.nestjs.com/modules)
- [NestJS validation](https://docs.nestjs.com/techniques/validation)
- [NestJS configuration](https://docs.nestjs.com/techniques/configuration)
- [NestJS lifecycle events](https://docs.nestjs.com/fundamentals/lifecycle-events)
- [NestJS OpenAPI introduction](https://docs.nestjs.com/openapi/introduction)