nodejs-best-practices
Node.js backend conventions — framework selection, API layering, error propagation, async performance, boundary validation, testing, security, and production gates. Use when architecting, building, reviewing, or deploying Node.js backend services. Not for browser/frontend JavaScript.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- nodejs-best-practices
- metadata
- { "category": "reference" }
- description
- Node.js backend conventions — framework selection, API layering, error propagation, async performance, boundary validation, testing, security, and production gates. Use when architecting, building, reviewing, or deploying Node.js backend services. Not for browser/frontend JavaScript.
02 资源文件 2
- 参考文档PRODUCTION.md4.0 KB
- 参考文档SECURITY.md4.3 KB
03 SKILL.md 正文
Node.js Best Practices
Evaluate project constraints and select explicit matches. For security-sensitive surfaces (auth, payments, user data, public traffic), load SECURITY.md. Prior to deployment or containerization, load PRODUCTION.md. Applying a section means every checklist item in it is accounted for: applied, or skipped with a stated reason.
1. Framework
Default: Fastify (high throughput, schema-first validation, native TypeScript). Select alternatives when constraints match:
| Condition | Choice | Rationale |
|---|---|---|
| Edge/serverless, or minimal-footprint general Node service | Hono | ~14KB, web-standard Request/Response; identical code on Node (@hono/node-server), Bun, Deno, edge runtimes |
| Enterprise codebases requiring structured DI | NestJS | Enforced modular conventions across teams (Express 5 by default; swap in the Fastify adapter for throughput) |
| Codebase with an established Express middleware ecosystem | Express | Express 5.x is stable; ecosystem compatibility |
| Type-safe full-stack RPC API | tRPC (internal TS monorepo) or oRPC (adds OpenAPI + REST compatibility) | Shared end-to-end TypeScript types |
2. Runtime and modules
- Runtime: Node.js Active LTS pinned via
.nvmrcandpackage.json#engines. Use nativenode --watchfor local development hot-reloading (eliminating nodemon). (Bun/Deno reserved for dedicated standalone tooling). - TypeScript: Use Node built-in type stripping (
--experimental-strip-typessince 22.6, unflagged since 23.6, stable since 24) for lightweight scripts and small services adhering to erasable syntax (interfaces, type aliases, type-only imports; enums, namespaces, and parameter properties need--experimental-transform-typesinstead of the stable stripper). Enforce with TypeScript'serasableSyntaxOnlycompiler option (TS 5.8+) so the codebase never silently drifts onto non-erasable syntax. Use standard build tools (tsc,tsup,tsx,esbuild) for production services and decorator-heavy frameworks (NestJS). - Modules: ESM (
import/export) by default. Import built-ins with explicitnode:prefix (node:fs/promises,node:crypto).
3. Architecture
Organize by business domain module (users/, orders/, billing/), each internally layered:
module/
├── routes/controller — HTTP transport, parameter extraction, boundary validation
├── service — business logic, framework-agnostic
└── repository — data access, database queries, ORM entities
Configuration resolves hierarchically: defaults < .env (loaded natively via node --env-file=.env) < environment variables. Load secrets strictly from environment variables or a secret manager.
4. Errors
Split errors into two distinct lifecycles:
- Operational errors (invalid input, resource not found, upstream timeout): Return structured HTTP responses and maintain continuous uptime.
- Programmer errors (unhandled exceptions, null dereferences): Log error context, stop accepting new connections, drain active requests, and forcefully terminate (
process.exit(1)) to let the container orchestrator restart a clean instance.
Handling rules:
- Throw custom domain error classes carrying HTTP status codes and machine-readable
codeidentifiers. - Consolidate error mapping in a single central error middleware at application root.
- Server logs receive stack trace, request parameters, and correlation ID; HTTP responses receive only user-safe message, status, and code.
- Return or
awaitall promises inside async handlers to preserve full asynchronous stack traces. - Attach error event listeners to streams, event emitters, and process unhandled rejection hooks.
5. Async and the event loop
- Execute independent asynchronous operations concurrently with
Promise.allorPromise.allSettled. - Offload CPU-bound tasks (cryptography, image transformations, heavy parsing) to worker threads, background queues, or dedicated services.
- Use
node:fs/promisesin request execution paths; reserve synchronousfsmethods exclusively for startup initialization. - Stream large file payloads and database query results rather than buffering in memory.
- Prefer modern built-in APIs over third-party packages:
node:crypto.randomUUID(),structuredClone(), globalfetch/Request/Response,node:util.parseArgs(),AsyncLocalStorage(node:async_hooks) for request context propagation, andperformance.eventLoopUtilization()(node:perf_hooks) for event loop health.
6. Validation
Validate all external inputs at the boundary: request body, query params, headers, environment variables, and third-party API responses.
Default: Zod v4 (2.3× smaller core bundle, up to 14× faster parsing, ~100× faster type instantiation than v3 — confirm the lockfile resolves v4, not legacy v3). Switch when constraints match: edge bundle size $\rightarrow$ Valibot, or zod/mini (~1.9KB) to stay on the Zod ecosystem; hot-path throughput $\rightarrow$ ArkType (Zod v4 has narrowed this gap significantly — benchmark before switching). Reject invalid payloads immediately at the route boundary before passing to domain services.
7. Security
Baseline requirements for every service (full hardening checklist: SECURITY.md — load for auth, payment, public-facing, or compliance-sensitive work):
- Validate all boundary inputs with strict schemas; parameterize all database queries.
- Hash passwords with
argon2id; pin JWT algorithms and verify signature and expiration. - Apply rate limiting on public and auth endpoints; enforce payload size caps.
- Enable security headers via
helmet; configure explicit CORS allowed domain origins. - Load secrets strictly from environment/secret managers; enforce committed lockfile via
npm ci --ignore-scripts, and verify package provenance/signatures (npm audit signatures) for critical dependencies. - Check regular expressions for ReDoS vulnerabilities to protect the single-threaded event loop.
8. Testing
Default runner: built-in node --test with node:assert — stable, with built-in mocking (mock.fn, mock.module, mock.timers), coverage, and watch mode. Switch to Vitest for snapshot testing (node:test's one missing feature), richer mocking ergonomics, or Jest compatibility. API integration tests via Supertest or native fetch against the test server instance.
Execution standards:
- Structure test cases with explicit context and expected outcome; organize bodies into Arrange–Act–Assert.
- Provide isolated database records per test case; mock external third-party HTTP dependencies.
- For critical paths (auth, billing, transactional workflows), assert all applicable side effects: response payload, database state mutations, outbound HTTP calls, queued jobs, and emitted telemetry.
9. Production
Pre-deploy baseline (full production and Docker checklist: PRODUCTION.md — load before deployment, containerization, or scaling work):
- Set
NODE_ENV=production, pin Active LTS Node, and executenpm cifrom committed lockfile. - Stream structured JSON logs directly to
stdoutwith request correlation IDs via Pino. - Instrument distributed tracing and metrics with OpenTelemetry (
@opentelemetry/sdk-node+ auto-instrumentations, bootstrapped vianode --import), correlated with Pino logs through shared trace/span IDs. - Maintain stateless processes; delegate TLS termination, compression, and static assets to a reverse proxy.
- Implement graceful shutdown on
SIGTERMwith active connection draining and hard exit timeout.
Decision checklist
Account for each item before completing implementation; clarify ambiguous constraints with the user:
- [ ] Framework selected according to routing and runtime requirements.
- [ ] Active LTS Node version pinned in
.nvmrcandpackage.json. - [ ] Codebase structured into domain modules with route, service, and repository layers.
- [ ] Central error-handling middleware registered with operational vs programmer error branching.
- [ ] Asynchronous request paths free of blocking synchronous calls or unhandled promise rejections.
- [ ] Input validation schemas attached to all route handlers and environment variables.
- [ ] Integration tests verify response payload and persistent state mutations for critical flows.
- [ ] Loaded SECURITY.md for public, auth, or sensitive data surfaces.
- [ ] Loaded PRODUCTION.md prior to containerization and deployment.
04 同仓库更多 Skills
unslop
Use when writing or editing prose a person will read, or when text sounds AI-generated.
show-me
Use when asked to show, diagram, or walk through how code fits together or what a change does, or before explaining a multi-file flow in prose.
pr
Use when writing or updating a pull request description, or before running `gh pr create`.
commit
Use when writing a commit message, or before running `git commit`.
write-specs
Spec a feature's observable behavior. Use when asked for requirements, when a request says what the system should do but not how, or to capture what a built system already guarantees. Not for how to build it (write-plan).
write-skills
Write, fix, or audit a skill's frontmatter, trigger description, and body. Use when a skill is asked for, never fires, or fires at the wrong moment. Not for a hook (write-hooks) or the plugin manifest and catalog.