Node Project Rules Checklist

Twenty-five rules every Node.js HTTP service or worker should satisfy before production traffic.

How to Use This Checklist

Walk top-to-bottom on new services before first deploy.
Re-audit quarterly or after major Node/framework upgrades.
Record pass/fail in an ADR appendix or team wiki; fix gaps in priority order.
Enforce mechanically via CI where possible (not README honor system).

Runtime & Process

Node 24 Active LTS pinned: engines and Docker FROM node:24.18.0 align.
Graceful shutdown: SIGTERM drains HTTP and closes DB pools within timeout.
Health and readiness routes: /health liveness; /ready checks DB when applicable.
No sync I/O on hot paths: fs.readFileSync banned in request handlers.
Bounded concurrency: Outbound HTTP and queue workers use limits (p-limit, pool size).

Security

Input validation at boundary: Zod or schema validation on every mutating route.
Secrets from environment or vault: No secrets in git; .env gitignored.
SSRF guards on outbound fetch: Block link-local and metadata IPs in user-supplied URLs.
Security headers and CORS explicit: Not framework defaults-only in production.
Dependency audit gate: npm audit --audit-level=high passes in CI.

API & Data

Consistent error JSON shape: { error: { code, message } } across routes.
Pagination on list endpoints: cursor or limit/offset documented max limits.
Idempotent mutations: Idempotency-Key or natural keys for POST that create resources.
Structured logging only: JSON logs; no raw console.log in src/.
Correlation ID on every request: Propagate X-Request-Id in logs and outbound calls.

Tooling & Quality

Lockfile committed; CI uses npm ci. Reproducible installs only.
Typecheck merge gate: tsc --noEmit on every PR.
Lint zero-warning policy: eslint --max-warnings 0.
Tests in CI: Unit required; integration for DB paths with isolated DB.
Import boundaries enforced: Apps do not import sibling apps in monorepos.

Operations & Architecture

Docker multi-stage build: Dev deps excluded from runtime image.
Config validated at startup: Process exits on invalid env schema.
Timeouts on outbound HTTP: No unbounded fetch to third parties.
ADR for framework and data store choices: Express/Fastify/Nest and ORM documented.
Runbook linked in README: On-call steps for OOM, bad deploy, DB outage.

Applying the Checklist in Order

Tier 1 (1-5, 6-10): Safety and security - block launch if failing.
Tier 2 (11-20): API consistency and quality gates - fix before GA traffic.
Tier 3 (21-25): Operational maturity - complete within first month production.

FAQs

Do workers need HTTP health routes?

Workers need process health via supervisor metrics; HTTP health applies to API services. Rule 3 adapts to worker heartbeat.

Can we skip idempotency for internal APIs?

Internal APIs still benefit from idempotency on create/charge endpoints to survive retries.

How do we enforce no console.log?

ESLint no-console in src/** plus CI lint gate (rule 18).

Is NestJS exempt from createApp pattern?

Nest uses Test.createTestingModule for tests but still needs graceful shutdown and same security/logging rules.

What if audit has no fix?

Document time-boxed exception (rule 10) with owner; do not silent-fail CI permanently.

How many rules for serverless Lambda?

Rules 1-2, 6-8, 11-15, 16-19 apply; Docker (21) becomes packaging config; shutdown (2) is runtime freeze aware.

Who signs off checklist?

Tech lead or reviewer tick on release ticket; store link to completed checklist.

How does this relate to other rule pages?

This checklist summarizes; deep dives live in Async, Security, API, Dependency, and Logging rule articles in this section.

Quarterly audit cadence enough?

Yes for stable services; re-run after Node major upgrade or incident postmortem action items.

Can rules be automated?

Aim for 16-20 fully in CI; 21-25 need docs and review but Docker/ADR can be template-enforced.

Async & Event Loop Rules - rules 4-5 detail
Security Rules - rules 6-10 detail
API Rules - rules 11-13 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.

Node Project Rules Checklist

Twenty-five rules every Node.js HTTP service or worker should satisfy before production traffic.

How to Use This Checklist

Walk top-to-bottom on new services before first deploy.
Re-audit quarterly or after major Node/framework upgrades.
Record pass/fail in an ADR appendix or team wiki; fix gaps in priority order.
Enforce mechanically via CI where possible (not README honor system).

Runtime & Process

Node 24 Active LTS pinned: engines and Docker FROM node:24.18.0 align.
Graceful shutdown: SIGTERM drains HTTP and closes DB pools within timeout.
Health and readiness routes: /health liveness; /ready checks DB when applicable.
No sync I/O on hot paths: fs.readFileSync banned in request handlers.
Bounded concurrency: Outbound HTTP and queue workers use limits (p-limit, pool size).

Security

Input validation at boundary: Zod or schema validation on every mutating route.
Secrets from environment or vault: No secrets in git; .env gitignored.
SSRF guards on outbound fetch: Block link-local and metadata IPs in user-supplied URLs.
Security headers and CORS explicit: Not framework defaults-only in production.
Dependency audit gate: npm audit --audit-level=high passes in CI.

API & Data

Consistent error JSON shape: { error: { code, message } } across routes.
Pagination on list endpoints: cursor or limit/offset documented max limits.
Idempotent mutations: Idempotency-Key or natural keys for POST that create resources.
Structured logging only: JSON logs; no raw console.log in src/.
Correlation ID on every request: Propagate X-Request-Id in logs and outbound calls.

Tooling & Quality

Lockfile committed; CI uses npm ci. Reproducible installs only.
Typecheck merge gate: tsc --noEmit on every PR.
Lint zero-warning policy: eslint --max-warnings 0.
Tests in CI: Unit required; integration for DB paths with isolated DB.
Import boundaries enforced: Apps do not import sibling apps in monorepos.

Operations & Architecture

Docker multi-stage build: Dev deps excluded from runtime image.
Config validated at startup: Process exits on invalid env schema.
Timeouts on outbound HTTP: No unbounded fetch to third parties.
ADR for framework and data store choices: Express/Fastify/Nest and ORM documented.
Runbook linked in README: On-call steps for OOM, bad deploy, DB outage.

Applying the Checklist in Order

Tier 1 (1-5, 6-10): Safety and security - block launch if failing.
Tier 2 (11-20): API consistency and quality gates - fix before GA traffic.
Tier 3 (21-25): Operational maturity - complete within first month production.

FAQs

Do workers need HTTP health routes?

Workers need process health via supervisor metrics; HTTP health applies to API services. Rule 3 adapts to worker heartbeat.

Can we skip idempotency for internal APIs?

Internal APIs still benefit from idempotency on create/charge endpoints to survive retries.

How do we enforce no console.log?

ESLint no-console in src/** plus CI lint gate (rule 18).

Is NestJS exempt from createApp pattern?

Nest uses Test.createTestingModule for tests but still needs graceful shutdown and same security/logging rules.

What if audit has no fix?

Document time-boxed exception (rule 10) with owner; do not silent-fail CI permanently.

How many rules for serverless Lambda?

Rules 1-2, 6-8, 11-15, 16-19 apply; Docker (21) becomes packaging config; shutdown (2) is runtime freeze aware.

Who signs off checklist?

Tech lead or reviewer tick on release ticket; store link to completed checklist.

How does this relate to other rule pages?

This checklist summarizes; deep dives live in Async, Security, API, Dependency, and Logging rule articles in this section.

Quarterly audit cadence enough?

Yes for stable services; re-run after Node major upgrade or incident postmortem action items.

Can rules be automated?

Aim for 16-20 fully in CI; 21-25 need docs and review but Docker/ADR can be template-enforced.

Async & Event Loop Rules - rules 4-5 detail
Security Rules - rules 6-10 detail
API Rules - rules 11-13 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.

Node Project Rules Checklist

Buscar en la documentación

Node Project Rules Checklist