| name | nodejs-backend |
| class | language |
| description | Node.js backend patterns: layered architecture, TypeScript, validation, error handling, security, deployment. Use when building REST APIs, REST endpoints, middleware, Express/Fastify/Hono/NestJS/Koa servers, tRPC procedures, Bun servers, or server-side TypeScript. |
| paths | **/*.ts,**/*.js,**/*.mjs,**/*.cjs |
Node.js Backend
Verify before implementing: For framework-specific APIs (Express 5, Fastify 5, Node.js 22+ built-ins), search current docs via search_docs before writing code. Training data may lag current releases.
Framework Selection
| Context | Choose | Why |
|---|
| Edge/Serverless | Hono | Zero-dep, fastest cold starts |
| Performance API | Fastify | Higher throughput than Express, built-in schema validation |
| Enterprise/team | NestJS | DI, decorators, structured conventions |
| Legacy/ecosystem | Express | Most middleware, widest adoption |
Ask user: deployment target, cold start needs, team experience, existing codebase.
Architecture
src/
├── routes/ # HTTP: parse request, call service, format response
├── middleware/ # Auth, validation, rate limiting, logging
├── services/ # Business logic (no HTTP types)
├── repositories/ # Data access only (queries, ORM)
├── config/ # Env, DB pool, constants
└── types/ # Shared TypeScript interfaces
- Routes never contain business logic
- Services never import Request/Response
- Repositories never throw HTTP errors
- Dependencies point inward only (Clean Architecture rule): routes -> services -> repositories. Never the reverse.
- For scripts/prototypes: single file is fine -- ask "will this grow?"
TypeScript Rules
- Use
import type { } for type-only imports -- eliminates runtime overhead
- Prefer
interface for object shapes (2-5x faster type resolution than intersections)
- Prefer
unknown over any -- forces explicit narrowing
- Use
z.infer<typeof Schema> as single source of truth -- never duplicate types and schemas
- Minimize
as assertions -- use type guards instead
- Add explicit return types to exported functions (faster declaration emit)
- Untyped package?
declare module 'pkg' { const v: unknown; export default v; } in types/ambient.d.ts
Validation
Zod (TypeScript inference) or TypeBox (Fastify native). Validate at boundaries only: request entry, before DB ops, env vars at startup. Use .extend(), .pick(), .omit(), .partial(), .merge() for DRY schemas.
Error Handling
Custom error hierarchy: AppError(message, statusCode, isOperational) → ValidationError(400), NotFoundError(404), UnauthorizedError(401), ForbiddenError(403), ConflictError(409)
Centralized handler middleware:
AppError → return { error: message } with statusCode- Unknown → log full stack, return 500 + generic message in production
- Async wrapper:
const asyncHandler = (fn) => (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
Codes: 400 bad input | 401 no auth | 403 no permission | 404 missing | 409 conflict | 422 business rule | 429 rate limited | 500 server fault
API Design
Contract-first: define route schemas (Zod schemas, Fastify JSON Schema, or OpenAPI spec) before writing handler logic. The schema is the contract -- implementation follows. Generate OpenAPI/Swagger docs from these schemas for interactive API documentation.
- Hyrum's Law awareness: every observable response field, ordering, or timing becomes a dependency for callers. Use Zod schemas or Fastify response schemas to control exactly what's serialized -- never return raw ORM objects or untyped objects from handlers.
- Addition over modification: add new optional fields rather than changing or removing existing ones. Removing a field from a response schema breaks callers silently. Deprecate first (mark in OpenAPI spec), remove in a later version.
- Consistent error envelope: all errors -- validation, auth, not-found, application -- must produce the same
{ error: { code, message, details? } } structure. Centralize in the error handler middleware. Callers build error handling once; inconsistent errors force per-endpoint special cases.
- Boundary validation: validate at the middleware/route handler level (Zod
.parse() on request body/params, Fastify schema validation). Services and repositories trust that input was validated at entry -- no redundant checks scattered through business logic.
- Third-party responses are untrusted data: validate shape and content of external API responses before using them in logic, rendering, or decision-making. A compromised or misbehaving service can return unexpected types, malicious content, or missing fields. Parse through a Zod schema before use.
- Resources: plural nouns (
/users), max 2 nesting levels (/users/:id/orders)
- Methods: GET read | POST create | PUT replace | PATCH partial | DELETE remove
- Versioning: URL path
/api/v1/
- Response:
{ data, pagination?: { page, limit, total, totalPages } }
- Queries:
?page=1&limit=20&status=active&sort=createdAt,desc
- Return
Location header on 201. Use 204 for successful DELETE with no body.
Async Patterns
| Pattern | Use When |
|---|
async/await | Sequential operations |
Promise.all | Parallel independent ops |
Promise.allSettled | Parallel, some may fail |
Promise.race | Timeout or first-wins |
Never use readFileSync or other sync methods in production -- use fs.promises or stream equivalents. Offload CPU work to worker threads (Piscina). Stream large payloads.
Production Resilience
- Fail-fast env validation: parse and validate all environment variables at startup with a Zod schema (
const env = envSchema.parse(process.env)). If invalid, crash before serving traffic. Never discover a missing env var on the first request that needs it.
- Health endpoints: expose both
/health (shallow, always 200 if process is alive) and /ready (deep, verifies database, cache, and critical dependencies are reachable). Load balancers probe /ready for traffic routing; monitoring probes /health for process liveness. Don't conflate them.
- Caching: Redis cache-aside for DB/API responses; in-memory LRU with TTL for hot paths. Always invalidate on writes.
- Load shedding:
@fastify/under-pressure (or equivalent) -- monitor event loop delay, heap, RSS; return 503 when thresholds exceeded.
- Response schemas: In Fastify, always define response schemas -- enables
fast-json-stringify for 2-3x faster serialization.
- Circuit breaker: use
opossum for outbound service calls. States: CLOSED (normal) -> OPEN (failing, return fallback) -> HALF_OPEN (probe). Prevents cascade failures when downstream services are down.
Discipline
- Simplicity first -- every change as simple as possible, impact minimal code
- Only touch what's necessary -- avoid introducing unrelated changes
- No hacky workarounds -- if a fix feels wrong, step back and implement the clean solution
- Before adding a new abstraction, verify it appears in 3+ places. If not, inline it.
- If a fix requires bypassing TypeScript (
as any, non-null assertions on untrusted data, // @ts-ignore), treat it as a design smell and find the typed solution
- Verify:
tsc --noEmit && npm test pass with zero warnings before declaring done
Verify
tsc --noEmit passes with zero errorsnpm test passes with zero failures- No TypeScript bypasses (
as any, @ts-ignore) in new code
References
- TypeScript config -- tsconfig, ESM, branded types, compiler performance
- Security -- JWT, password hashing, rate limiting, OWASP
- API design patterns -- pagination, filtering, sorting, deprecation
- Database & production -- connection pooling, transactions, Docker, logging
