nestjs stack
- Repo stars 0
- Author repo skills-registry
- Domain
- Design
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Env read
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
NestJS-specific implementation of DDD + Hexagonal + CQRS patterns. For the underlying theory (aggregates, domain events, architecture layers), see `engineering-toolkit:engineering-foundations`. This skill covers the NestJS-specific HOW. Before applying any topic, read its reference file in `reference/`.
## Topics
| Topic | When to Use | Reference |
|---|---|---|
| **Error Handling** | Exception filters, domain error -> HTTP mapping | `reference/error-handling.md` |
| **Config** | Environment variables, config modules, validation | `reference/config.md` |
| **Auth** | Guards, JWT strategies, RBAC | `reference/auth.md` |
| **API Design** | Endpoints, DTOs, Swagger, pagination | `reference/api-design.md` |
| **Code Structure** | Where to place code, resolving circular imports | `reference/code-structure.md` |
| **Logging** | Structured logging with Pino, correlation IDs | `reference/logging.md` |
| **Domain Model (NestJS)** | @nestjs/cqrs AggregateRoot, EventPublisher | `reference/nestjs-domain-model.md` |
| **TypeORM Migrations** | Creating database migrations | `reference/typeorm-migrations.md` |
| **TypeORM Queries** | Writing queries and transactions | `reference/typeorm-queries.md` |
## Architecture Overview
```
+------------------------------------------------------------------+
| PRESENTATION LAYER |
| apps/ (HTTP Controllers, DTOs, Request/Response handling) |
+------------------------------------------------------------------+
| APPLICATION LAYER |
| modules/ (Commands, Queries, Handlers, Events) |
+------------------------------------------------------------------+
| DOMAIN LAYER |
| libs/common/domain/ (Entities, Value Objects, Enums) |
+------------------------------------------------------------------+
| INFRASTRUCTURE LAYER |
| libs/ (Repositories, External APIs, Database, Messaging) |
+------------------------------------------------------------------+
```
## Quick Decision Guide
```
Writing an endpoint?
-> reference/api-design.md + reference/code-structure.md
Handling errors?
-> reference/error-handling.md
Setting up config/env?
-> reference/config.md
Adding authentication?
-> reference/auth.md
Writing a database query?
-> reference/typeorm-queries.md
Creating a migration?
-> reference/typeorm-migrations.md
Implementing a domain model with events?
-> reference/nestjs-domain-model.md
Adding logging?
-> reference/logging.md
```
## Gotchas
Claude-specific failure modes in NestJS codebases:
- **Throwing `HttpException` from domain/application layer** — Claude defaults to HTTP exceptions everywhere. Domain layer must throw domain-specific exceptions; the exception filter maps them to HTTP responses.
- **Using `process.env.X` instead of ConfigService** — Claude reaches for `process.env` out of habit. Always inject `ConfigService` and use `.get()`.
- **Putting auth logic in services** — Claude tends to add `if (!user.isAdmin)` checks inside service methods. Auth belongs in guards; services receive already-validated context.
- **Returning entities directly from controllers** — Claude skips DTO mapping when "it's the same shape anyway." Always use response DTOs, even if they mirror the entity — the contract must be explicit.
- **Circular imports between modules** — Claude creates circular dependencies when wiring cross-module services. Use `forwardRef()` as last resort; prefer restructuring.
- **Logging message-first instead of context-first** — Claude writes `logger.log('User created', { userId })` instead of `logger.log({ userId }, 'User created')`. Pino expects context object first.
- **Raw SQL when QueryBuilder suffices** — Claude jumps to raw SQL for anything beyond `.find()`. Follow the hierarchy: built-in methods > QueryBuilder > raw SQL.
- **Forgetting to release QueryRunner** — Must always release in a `finally` block. Claude sometimes puts `release()` only in the happy path.
- **Importing from other module's internal paths** — Use the module's public API (barrel exports), not deep `../other-module/internal/file` imports.
## Key Rules (Always Apply)
- **Domain layer MUST NOT import HTTP exceptions** — use domain exceptions, map in filters
- **Never access `process.env` directly** — use ConfigService
- **Auth in guards, not in services** — domain receives validated user context
- **DTOs for all input/output** — never expose entities directly
- **Relative imports within modules** — path aliases across modules
- **Context-first logging** — structured fields before message string
- **Query hierarchy** — built-in methods first, query builder second, raw SQL last resort
- **Release query runners** — always in a `finally` block
---
> Source: [anpham1925/claude-marketplace](https://github.com/anpham1925/claude-marketplace) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
Sections and files
Listed in source order.
sections -> Topics → Architecture Overview → Quick Decision Guide → Gotchas → Key Rules (Always Apply)
terms -> Error Handling · Config · Auth · API Design · Code Structure · Logging · Domain Model (NestJS) · TypeORM Migrations
files/cmd -> engineering-toolkit:engineering-foundations · reference/ · reference/error-handling.md · reference/config.md · reference/auth.md · reference/api-design.md · reference/code-structure.md · reference/logging.md
body sha256 -> 58701f688d03
Topics
Topic · When to Use · Reference Error Handling · Exception filters, domain error -> HTTP mapping ·
reference/error-handling.mdConfig · Environment variables, config modules, validation ·reference/config.mdAuth · Guards, JWT strategies, RBAC ·reference/auth.mdAPI Design · Endpoints, DTOs, Swagger, pagination ·reference/api-design.mdGotchas
Claude-specific failure modes in NestJS codebases: Throwing
HttpExceptionfrom domain/application layer — Claude defaults to HTTP exceptions everywhere. Domain layer must throw domain-specific exceptions; the exception filter maps them to HTTP responses. Usingprocess.env.Xinstead of ConfigService — Claude reaches forprocess.envout of habit. Always injectConfigServiceand use.get().Key Rules (Always Apply)
Domain layer MUST NOT import HTTP exceptions — use domain exceptions, map in filters Never access
process.envdirectly — use ConfigService Auth in guards, not in services — domain receives validated user context DTOs for all input/output — never expose entities directly Relative imports within modules — path aliases across modules