Docs · NestJS / Architecture / Feature Modules
NestJS Feature Module Runbook
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:
@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.
@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.
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
Agent access
Choose a representation.
Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.