{"id":49,"type":"docs","title":"NestJS Feature Module Runbook","slug":"nestjs-feature-module-runbook","canonicalUrl":"https://docs.phatysd.me/content/nestjs-feature-module-runbook","status":"published","revision":1,"publishedAt":"2026-09-19T17:51:06.174Z","updatedAt":"2026-09-19T17:51:06.174Z","hierarchyPath":"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","canonicalUrl":"https://docs.phatysd.me/content/nestjs-modules-are-the-boundary"}],"body":"# NestJS Feature Module Runbook\n\nNestJS gives a service a strong application structure through modules,\ncontrollers, and providers. Use that structure to make ownership visible:\ncontrollers translate transport input, providers implement use cases, and\nmodules define the feature boundary.\n\n## Build one feature at a time\n\nA feature module should own the controllers and providers needed for one\nbusiness capability:\n\n```ts\n@Module({\n  imports: [DatabaseModule],\n  controllers: [OrdersController],\n  providers: [OrdersService, OrdersRepository],\n  exports: [OrdersService],\n})\nexport class OrdersModule {}\n```\n\nImport the feature module from the root module. Avoid putting every provider in\n`AppModule`; the root module should primarily compose the application.\n\n## Keep controllers thin\n\nControllers should own route decorators, request parameters, DTO boundaries,\nand response status decisions. Providers should own business rules and\norchestration. This separation lets unit tests exercise the use case without\nbooting the whole HTTP application.\n\n```ts\n@Controller(\"orders\")\nexport class OrdersController {\n  constructor(private readonly orders: OrdersService) {}\n\n  @Post()\n  create(@Body() input: CreateOrderDto) {\n    return this.orders.create(input);\n  }\n}\n```\n\n## Validate at the application boundary\n\nUse DTOs and a global `ValidationPipe` for a consistent request contract. A\ntypical production policy enables transformation only when the DTO and\napplication semantics expect it, whitelists known properties, and rejects\nunexpected input rather than silently accepting a larger payload.\n\n```ts\napp.useGlobalPipes(\n  new ValidationPipe({\n    whitelist: true,\n    forbidNonWhitelisted: true,\n    transform: true,\n  }),\n);\n```\n\nValidation is not authorization. A DTO can prove that a field is shaped\ncorrectly; a provider or guard still needs to decide whether the caller may\nperform the operation.\n\n## Keep configuration explicit\n\nLoad configuration once, validate required environment variables, and inject\nconfiguration through the Nest application rather than reading `process.env`\nthroughout feature code. Separate safe defaults from values that must be\npresent in production, such as database URLs, signing keys, and external API\ncredentials.\n\nNever include secrets in configuration logs or error responses.\n\n## Plan lifecycle and API exposure\n\nEnable shutdown hooks when providers need to close database pools, queues, or\nother resources. Test that SIGTERM drains the application within the platform\ndeadline. If Swagger is enabled, decide whether its UI and raw definitions\nshould be public in production; API documentation exposure is an operational\nchoice, not an automatic requirement.\n\n## Production checklist\n\n- Every feature has a module with explicit imports, controllers, providers, and exports.\n- Controllers contain transport concerns; providers contain use cases.\n- DTO validation is enabled at the application boundary.\n- Unknown properties and malformed payloads have a deliberate policy.\n- Guards and service-level authorization protect sensitive actions.\n- Required configuration is validated before the server accepts traffic.\n- Shutdown hooks close external resources and are exercised with SIGTERM.\n- Swagger exposure matches the production security policy.\n\n## References\n\n- [NestJS modules](https://docs.nestjs.com/modules)\n- [NestJS validation](https://docs.nestjs.com/techniques/validation)\n- [NestJS configuration](https://docs.nestjs.com/techniques/configuration)\n- [NestJS lifecycle events](https://docs.nestjs.com/fundamentals/lifecycle-events)\n- [NestJS OpenAPI introduction](https://docs.nestjs.com/openapi/introduction)"}