nodejs-best-practices

Node.js Best Practices

Use this skill for Node.js runtime decisions rather than framework-specific concerns.

Scope

• ESM vs CommonJS and import strategy
• async error handling and process boundaries
• streams, backpressure, and pipeline-based processing
• tests, flaky teardown, and stuck processes
• graceful shutdown and resource cleanup
• environment and configuration handling
• logging, profiling, and performance investigation
• modern TypeScript execution in Node.js

Default path

1. Identify whether the task is runtime behavior, module loading, stream processing, test stability, or operational hardening.
2. Keep I/O boundaries explicit: files, network, child processes, queues, and caches.
3. Prefer async and await with clear error boundaries over nested Promise chains.
4. For stream-heavy work, prefer pipeline() and make backpressure visible in the design.
5. Separate startup config validation from request or job execution.
6. On shutdown, stop intake first, then drain in-flight work, then close external resources.
7. When debugging performance, reproduce first, measure second, then optimize.

When to deviate

• Use CommonJS only when the runtime, tooling, or published package surface still requires it.
• Reach for worker threads only when the bottleneck is truly CPU-bound and isolation helps.
• Move to framework skills when the problem is no longer Node runtime design but framework behavior.

Guardrails

• Do not mix ESM and CommonJS patterns casually in the same runtime surface.
• Do not treat process.env reads as unbounded global state. Normalize config once.
• Do not swallow async errors in background jobs or event handlers.
• Do not build large file or ETL flows around .pipe() chains if pipeline() gives better failure handling.
• Do not rely on tests passing locally if teardown is nondeterministic.
• Treat native TypeScript execution features as runtime-sensitive and verify them against the current Node docs before standardizing on them.