/nestjs-architecture

Design NestJS module boundaries and provider ownership. Use only when structuring feature/core/shared modules, controller-service boundaries, or provider lifetime; defer JWT/security, caching, and unrelated request-pipeline recipes.

hoangnguyen0403@hoangnguyen0403

GitHub

From plugin

agent-skills-standard

538200 skills1 MCP

Install

$ npx -y skills add hoangnguyen0403/agent-skills-standard --skill nestjs-architecture --agent claude-code

How it fires

How this skill gets triggered: by you, by Claude, or both.

Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/nestjs-architecture

Context preview

The summary Claude sees to decide when to auto-load this skill.

Design NestJS module boundaries and provider ownership. Use only when structuring feature/core/shared modules, controller-service boundaries, or provider lifetime; defer JWT/security, caching, and unrelated request-pipeline recipes.

SKILL.md

nestjs-architecture.SKILL.md

name: nestjs-architecture
description: Design NestJS module boundaries and provider ownership. Use only when structuring feature/core/shared modules, controller-service boundaries, or provider lifetime; defer JWT/security, caching, and unrelated request-pipeline recipes.
metadata:
  triggers:
    files:
    - '**/*.module.ts'
    - 'main.ts'
    keywords:
    - NestFactory
    - Module
    - Controller
    - Injectable

NestJS Architecture Expert

Priority: P0 (CRITICAL)

Design feature modules with singleton-first providers and explicit request-pipeline choices.

Decision Map

**Module role**: Feature Modules (Auth) vs Core (Config/DB) vs Shared (Utils). Feature owns its controllers, application services, and adapters. Shared exports stateless helpers only.
**Provider scope**: default singleton. Use request scope only for tenant context, request-local caching, or request tracking. Treat request scope as a measured exception.
**Pipeline choice**: middleware for raw HTTP concerns, guard for access decisions, pipe for validation/transforms, interceptor for cross-cutting request/response behavior, filter for error translation.

Recipe

1. **Create bounded feature**: module + controller + application service + persistence adapter. 2. **Keep controller thin**: Thin controllers, fat services. No business in Controller. Move logic to Service. 3. **Register dependencies once**: imports for modules, providers for services, exports only for true consumers. `@InjectRepository()` dependencies need `TypeOrmModule.forFeature([...])`. 4. **Validate at edges**: DTO validation pipes for incoming data; never trust raw payloads in services. 5. **Check circular imports**: check circular dependencies with `madge`; refactor contracts first and use `forwardRef()` only as last resort.

Verify

[ ] Feature module owns one business capability, not a mixed grab bag.
[ ] Providers are singleton unless request scope has a written reason.
[ ] Guard/pipe/interceptor/filter placement matches the request lifecycle.
[ ] Config uses `@nestjs/config` or a typed config layer, not scattered `process.env`.
[ ] Dependency Integrity: DB repositories, queues, and clients are registered in the module graph, not manually instantiated.

Anti-Patterns

**No request scope by default**: Singleton first; justify heavier scope.
**No business logic in controllers**: Delegate orchestration to services/use cases.
**No entity leakage**: Don't return ORM entities; return DTOs or response models.
**No manual instantiation**: Use DI; never `new Service()` inside Nest code.