Nestjs

NestJS + Prisma

> Keep layers thin and one-directional: controller → service → repository. Each layer does one job.

Rules (firm)

Layering

• Controllers handle HTTP only — no business logic, no DB access. One per resource. Return DTOs, not entities. Explicit @HttpCode() when non-default.
• Services hold all business logic. Constructor-injected deps. Throw specific exceptions (NotFoundException, …), never raw Error.
• Repositories are the only layer touching the DB client. Transactions for multi-step mutations.

Modules

• One module per feature under src/modules//; shared infra in src/common/. Export only the public surface. forwardRef() only when a circular dep is truly unavoidable. Register global pipes/filters/guards once in the app module.

DTOs & validation

• Every inbound payload is a DTO with class-validator decorators — validate at the boundary, trust nothing. Separate Create/Update DTOs (compose with PartialType/PickType/OmitType). @ApiProperty() on response DTOs.

Errors & config

• Global exception filter → one consistent error shape. Never return raw DB errors; stack traces in dev only.
• All config via ConfigService/env — no hardcoded URLs, keys, ports. Validate required config on startup (fail fast).

Types (NestJS-specific)

• No any — use unknown then narrow at the boundary. enum for finite value sets. readonly on DTO/config fields.

Audit checks (binary, when reviewing endpoints)

• Database — only repos/services query; filtered/sorted columns indexed; no N+1; pagination clamped (min(max(limit,1),100)).
• Security — every protected route guarded or explicitly @Public; keys server-side only; parameterized queries only.
• Hygiene — no unused imports/providers; no console.log; no commented-out code; no TODO without an issue; lint clean.
• Performance — AbortSignal.timeout() on external fetches; cache hot data with TTL; bounded queries; Promise.allSettled for parallel; intervals cleared in onModuleDestroy.
• API surface — Swagger decorators; consistent response wrapper; versioned routes; correct status codes; query params validated via DTOs.

Production concerns (Detect → Check → Suggest — never auto-enforce)

For each: detect if handled (grep lib/decorator/table/header, ask if upstream) → if present, check depth → if absent, suggest with tradeoffs; do not retrofit without approval.

| Concern | Detect / key check | If absent | |---------|-------------------|-----------| | Rate limiting | @Throttle, gateway/WAF; stricter on auth, tenant-aware key | Flag brute-force/cost risk; offer throttler or upstream | | Idempotency keys | idempotency-key, replay table; returns original response | Ask which mutations are critical (payments) → offer pattern | | Retry + backoff | p-retry/circuit breaker; bounded, jittered, idempotent-only | Offer p-retry+timeout; warn: retry+no-idempotency = dupes | | Webhook signatures | verify before parse; raw body; timestamp check | Security gap if webhooks exist — flag loud, give provider snippet | | Graceful shutdown | enableShutdownHooks(), SIGTERM drain | In containers, missing = dropped requests per deploy | | Health/readiness | /health liveness pure; /ready checks deps | Required behind orchestrators; offer @nestjs/terminus | | Correlation IDs | x-request-id, AsyncLocalStorage, in every log | Multi-service debugging needs it; offer middleware | | Soft vs hard delete | deletedAt + global filter; GDPR hard-delete path | Ask GDPR/restore needs; else hard delete is fine | | Audit logs | append-only table; actor/target/before-after | Flag for B2B/admin/regulated; skip for solo/consumer | | DB pool + timeouts | connection_limit, statement_timeout | Offer defaults; outages trace to pool exhaustion | | Env-aware logging | level/format by env; secrets redacted at logger | Offer pino; redaction list is non-negotiable |

Verify, don't guess (cross-boundary)

Reading a DB column, calling an SDK, consuming an env var, importing a shared type → read the source of truth first (schema, .env.example, SDK typings, OpenAPI). Can't read it? Ask a concrete question. Never guess a field name — "probably user_id" is the same bug as "definitely user_id" when it's userId. Surface unverifiable assumptions to the user.

Schema changes (Prisma)

1. Edit prisma/schema.prisma → 2. npx prisma generate → 3. npx prisma migrate dev --name (e.g. add-user-preferences) → 4. npx tsc --noEmit + lint → 5. update consumers (interfaces, services, repositories) → 6. if another service consumes this schema, remind the user to run the consumer-side sync/regenerate step.

• Never edit an applied migration — create a new one.
• If a migration fails, check for data violating new constraints before retrying.
• In schema-owner / schema-consumer splits, only the owner repo creates migrations; consumers pull schema + regenerate the client.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pixelcrafts-app
• Source: pixelcrafts-app/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.