nestjs-dev-guidelines

NestJS Dev Guidelines

A complete set of production-grade NestJS and Nest-style Node.js backend standards. Apply these rules whenever working on a codebase that already uses NestJS concepts such as modules, controllers, providers/services, DTOs, pipes, and guards, or when the task is explicitly about designing those patterns. Think like a senior backend engineer: consistency over cleverness, explicit over implicit, boundaries over shortcuts.

How to use this skill

1. Before writing or reviewing code, scan references/00-execution-discipline.md and the Non-Negotiables below.
2. For file placement, module boundaries, or refactor decisions, use the Decision Trees.
3. For deep detail on a topic, open the matching references/NN-<topic>.md file. Each is self-contained: TL;DR, rules, good/bad examples, anti-patterns, and a review checklist.
4. When reviewing a PR, run through references/29-code-review-checklist.md + the topic references relevant to the diff.

Scope and precedence

Use this section when the repo is "backend TypeScript" but not obviously a standard NestJS app.

1. NestJS-first scope. Apply this skill directly when the repo already uses NestJS primitives (@Module, controllers, providers/services, guards, pipes, DTOs) or when the user is asking you to design a NestJS solution.
2. Plain Node backends are partial-match only. If the repo is plain Express/Fastify/Hono/Koa without NestJS primitives, use only the cross-cutting guidance here (validation, contracts, authz, DB design, testing, observability). Do not force Nest-specific APIs, decorators, or folder structure onto that codebase.
3. Protect outcomes first, tooling second. The non-negotiables below are invariants first and implementation defaults second. Centralized input validation, stable response contracts, structured redacted logging, ownership checks, and test coverage matter more than the exact library used to achieve them.
4. Follow equivalent-safe repo conventions. If the repo already uses a different but healthy mechanism that preserves the same safety/property boundary (for example Zod instead of class-validator, or a repo-standard structured logger instead of nestjs-pino), follow the repo rather than rewriting it mid-task.
5. Escalate harmful conflicts. If the existing pattern weakens security, correctness, data integrity, or a stable contract, call it out explicitly and ask before normalizing or widening that pattern.

Execution discipline

Apply these rules before touching NestJS-specific details. They exist to reduce the usual LLM failure modes: silent assumptions, overbuilt code, broad refactors, and unverified fixes.

1. Think before coding. State assumptions. If the task is ambiguous, ask or explicitly list the plausible interpretations instead of silently picking one.
2. Verify volatile facts. Versions, package APIs, model IDs, install commands, and CLI flags change. Verify them against official docs and the repo before recommending — do not recall from memory. See 35-source-of-truth-freshness.md.
3. Search before writing new code. Check the current module first, then shared/common/core code for an existing util, DTO, service, guard, interceptor, repository, or pattern you can reuse.
4. Fix root causes, not trigger hacks. Do not patch broad behavior with one-off regexes, hardcoded phrases, or manual if/then rules unless the product requirement is literally deterministic rule-based routing.
5. Prefer the smallest correct change. No speculative flags, abstractions, helpers, config, or edge-case handling unless the task or codebase clearly needs them.
6. Make surgical edits. Touch only the lines needed for the request. Do not clean up unrelated code, comments, or formatting just because you are nearby.
7. Search and update the full impact surface. If a shared function, contract, DTO, type, or behavior changes, scan and update callers, tests, docs, examples, and related flows until the whole change is consistent.
8. Ask before changing shared behavior. If reusing existing code requires changing shared semantics, multiple callers, or a reusable contract, stop and confirm instead of silently widening the blast radius.
9. Define what success looks like. Convert vague requests into checks you can verify: regression test, unit test, e2e test, typecheck, lint, build, or a concrete manual check.
10. Stop when confused. Name the uncertainty early. Short clarifying questions are cheaper than rewriting the wrong code.

Open references/00-execution-discipline.md for the full checklist and examples.

Non-negotiables (protect these outcomes; prefer these patterns)

Each rule has a Why so you can reason about edge cases instead of applying it blindly.

1. No business logic in a controller. Controllers validate input, delegate to a service, and shape the response. Nothing else. Why: controllers are thin HTTP adapters. Logic in them can't be unit-tested without booting the framework, and it pulls HTTP concerns into domain code. See 04-code-quality.md.
2. Every external input goes through a DTO. Body, query, and param DTOs use class-validator; ValidationPipe is global with whitelist: true, forbidNonWhitelisted: true, transform: true. Why: DTOs are the one choke point where unknown fields, bad types, and injection payloads are stopped. Skipping one means you trust the client. See 09-validation.md.
3. Never trust the client. Every ID from the URL is checked against the authenticated user/org's ownership. Filter and sort fields are whitelisted. Mass-assignment is prevented by whitelist. Why: IDOR and mass-assignment are the two most common application-level breaches. They only exist when code assumes "if the token is valid, the payload is fine." See 11, 12.
4. One module owns its tables. No cross-module raw DB reads. If module B needs data from module A, call A's service (DI) or subscribe to A's events. Why: shared table access makes every schema change a cross-team coordination problem. Modules become coupled through the DB instead of through APIs. See 03-module-design.md.
5. snake_case in the database, camelCase in code. Tables plural, columns snake_case, primary keys id, foreign keys <entity>_id. Why: each ecosystem has a convention; mixing them creates a lifetime of mapping bugs and makes ad-hoc SQL painful. Pick the convention of the side that's hardest to change (the DB). See 13-database-design.md.
6. Responses follow one stable contract. Single-resource success returns the object itself; list success returns { data, meta }; errors return { code, message, details?, traceId } with the correct HTTP status. Why: a consistent contract lets clients write one error handler and one pagination handler that works everywhere, and lets support triage issues by traceId. See 07, 10.
7. Pagination is required for any list endpoint. Choose cursor/keyset for sequential browsing over mutable or large data; choose offset when page-number navigation or exact totals are real product requirements. Both return meta with pagination info. Why: an unpaginated list is a latent OOM and a latent DB outage. The right pagination model depends on UX, consistency requirements, and scale. See 08.
8. Secrets come from env only — validated with Zod at boot. No secrets in code, no secrets in logs. Invalid env = crash before serving traffic. Why: a missing/malformed env var caught at boot is a minor incident; caught at runtime on the hot path, it's a customer outage. See 20, 11.
9. Structured logs, redacted. nestjs-pino with JSON in prod; redact authorization, cookie, set-cookie, password, token. Correlation ID on every log line. Why: plain-text logs can't be queried at scale, and one unredacted Authorization header is a credential leak with a long tail. See 21.
10. Test at boundaries, not internals. Unit-test services with mocked dependencies; e2e-test controllers through the HTTP layer; never mock the class under test. Why: mocking the code under test just re-asserts the mock. Tests should verify the contract (HTTP, DB, external calls), not the implementation. See 23.
11. Tenant identity is server-derived and layered. In a multi-tenant app, tenant/org id comes from the authenticated session/JWT, never from the request body. Guards, services, and repositories each filter by tenant; tests prove tenant A cannot see tenant B's data. Why: cross-tenant leaks almost always come from a single missing WHERE tenant_id = ? or a client-supplied id that was trusted too early. Layered enforcement means a bug in one layer does not leak data. See 33.

Senior-engineer mindset (decision trees)

Full decision trees live in references/05-thinking-decision-trees.md. Short version:

Where does this file go?

• Business feature → modules/<feature>/
• App-wide infra (auth, redis, mail) → core/<name>/
• Generic utility (pipe, decorator, type) → common/<kind>/
• External API client (Stripe, AWS) → integrations/<provider>/
• CLI/CRON job → commands/<name>.command.ts
• Domain event publisher/listener → events/<event-name>/

Should I create a new module?

• Does it own its own DB tables? → Yes, new module.
• Does it have its own lifecycle / domain logic? → Yes, new module.
• Is it just a helper used by one module? → No, put it inside that module's utils/.
• Is it used by 2+ modules but owns no data? → common/ utility.

Should I refactor this now?

• Am I already editing this code? → Yes, clean as you go.
• Is it blocking my current feature? → Yes, refactor minimally.
• Is it just "ugly"? → No, note it and move on.

Should I skip the test?

• Is it a controller? → No. E2E test always.
• Is it a service with branching logic? → No. Unit test always.
• Is it a thin pass-through (e.g., findById) with no logic? → Skipping is OK; the e2e test of the controller covers it.
• Is it a DTO / type? → No test needed; the compiler is the test.

Rule index (one line per reference)

Read the full reference file when you need detail. The number prefix is for stable ordering.

When to deep-read

Code review mode

When the user asks you to review a PR, changes, or a diff:

1. Read the diff top-to-bottom first — understand intent before critiquing.
2. Walk the 29-code-review-checklist.md — mark each item pass/fail/NA.
3. For each fail, cite the specific section in the relevant reference file (e.g., "business logic in controller — see 04-code-quality.md → Layering / Anti-patterns").
4. Distinguish blockers (security, data-loss risk, non-negotiable rule broken) from suggestions (style, minor naming, optional refactor). Don't block on suggestions.
5. If you spot an anti-pattern, link to 30-code-review-anti-patterns.md and quote the good version.
6. End the review with: (a) blockers (numbered), (b) suggestions (bulleted), (c) approval conditional on blockers being resolved.

AI product appendix

If the project is an AI product backend (LLMs, agents, RAG, vector store, streaming, usage- based billing), also read:

• 26-ai-product-patterns.md — provider-agnostic LLM gateway, retry/fallback
• 27-ai-streaming-sse.md — SSE endpoint patterns, cancel, heartbeat
• 28-ai-usage-metering-cost.md — token + cost metering, quota enforcement
• 22-observability.md — Langfuse/Helicone for LLM tracing

Everything else (auth, DB, error handling, testing) applies identically to AI products — the AI bit is a module, not a framework.

Meta

• Execution discipline before framework detail. Small, explicit, verified changes beat fast, broad, clever ones.
• Rules > style preferences. These are rules because they prevent real bugs or pay back in maintainability. Style debates are not covered.
• Consistency > cleverness. If a repo has an established equivalent-safe pattern that differs from this skill, follow the repo unless the pattern is actively harmful.
• When in doubt, keep it boring. Boring code is easy to review, easy to onboard, and easy to replace. That is the point.*