Node.js Rules Best Practices

How to turn Node service rules from documentation into enforced, auditable engineering practice.

How to Use This List

• Pair with the Node Project Rules Checklist each quarter.
• Every rule should map to CI, lint, or code review - not honor system.
• Platform team maintains templates that bake in enforceable defaults.

A - Enforcement Mechanics

• CI fails on lint, typecheck, test, audit - not warnings in README. Rules without gates decay in weeks.
• Templates include .npmrc engine-strict, ESLint, sample test, Dockerfile. New repos start compliant.
• PR checklist links rule checklist for major features. Human gate for rules automation cannot cover.
• Supersede ADRs when reversing decisions. Git history explains why rules changed.
• Quarterly rule audit ticket. Owner scans checklist pass/fail per service catalog.

B - Runtime & Reliability

• Graceful shutdown integration tested. SIGTERM test in CI or staging deploy script.
• Readiness differs from liveness. DB check only on /ready to avoid cascade kill during blips.
• Event loop and sync IO rules in lint/architecture review. Block readFileSync in src/ via custom rule or grep CI.
• Outbound timeouts mandatory in HTTP client wrapper. Single fetchWithTimeout used org-wide.
• Worker jobs carry correlation IDs from triggering request. Trace joins across async boundaries.

C - Security & Dependencies

• Zod (or equivalent) on every mutating route. No raw req.body deep in services.
• Secret scanning on push. GitHub secret scan plus gitleaks in CI.
• SSRF wrapper required for user URLs. No bare fetch(userInput) anywhere.
• Weekly dependency audit schedule. Not only when Renovate opens PRs.
• RFC before new production dependency. knip prevents unused deps accumulating.

D - API & Observability

• Global error handler single JSON shape. Clients and BFFs depend on consistency.
• Idempotency keys on financial mutations. DB unique index enforces; not application-only cache.
• Structured JSON logs only; Pino or equivalent. no-console in src/.
• Metrics for golden signals: latency, traffic, errors, saturation. RED metrics minimum per service.
• OpenAPI or Zod schemas published for public APIs. Contract source of truth documented.

E - Culture & Ownership

• On-call runbook linked and tested after major changes. Rules 21-25 operational slice.
• Incidents update rules or ADRs when gaps found. Postmortem actions become checklist items.
• Junior onboarding walks checklist tier 1. Security and runtime before feature velocity.
• Platform exceptions time-boxed. engine-strict waivers expire with ticket ID.
• Rules taught via code review examples, not slides only. Link rule doc in review comments.

FAQs

Related

• Node Project Rules Checklist - 25 rule audit
• ADR Template for Node - document decisions
• Security Rules - security rule detail

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.