node-modern

Modern Node.js

Selection card

• Task: Node runtime APIs, ESM and async cancellation.
• Start: Locate the affected route/component and its runtime/lockfile.
• Finish: apply the acceptance checks below; report observed results and unresolved constraints.

Overview

Current Node.js (v26.11.1 as checked 2026-10-09) ships natively what older code pulled from npm: native TypeScript type stripping (node file.ts), native .env loading (node --env-file), built-in SQLite (node:sqlite), global WebSocket, Promise.withResolvers(), global fetch, AbortSignal.timeout, node:test, Web Streams, and node --run. Prefer the platform when its semantics fit; do not remove needed capabilities merely to reduce dependency count.

Rules

1. Pre-flight: Inspect repo runtime & live Node.js LTS schedule first. Check package.json "engines", .nvmrc, .node-version, and check node -v to determine the active engine. Check the official Node.js release schedule online to ensure target runtime aligns with active LTS or the requested latest stable channel; verify support status from the current release schedule.
2. Match the module system. In an ESM package ("type": "module" or .mjs) write ES import statements, with explicit file extensions on relative imports when the project compiles with NodeNext. Don't convert a CommonJS package to ESM as a side effect of another change.
3. Import built-ins with the node: prefix (node:fs/promises, node:path, node:sqlite).
4. Prefer native platform features over npm bloat:
   • Use native node --env-file=.env instead of installing dotenv.
   • Use native globalThis.fetch() instead of axios or node-fetch.
   • Native WebSocket covers standard clients; verify the required client/server features before replacing ws.
   • Use native node:sqlite for local structured caching and data storage.
   • Use native node:crypto randomUUID() instead of uuid.
   • Use Promise.withResolvers() instead of hand-rolled deferred promises.
5. Give every operation that can wait a deadline: pass an AbortSignal to fetch calls, child processes, and timers; combine user cancellation with a timeout using AbortSignal.any.
6. Handle ENOENT by reading inside try/catch and branching on err.code; checking access first is a race (TOCTOU).
7. Never block the event loop in a server or CLI hot path: no *Sync fs calls or CPU-heavy loops on request paths.
8. Pass arguments to child processes as an array (execFile/spawn), never by interpolating into a shell string.
9. Every promise is awaited, returned, or explicitly handled; let entry points report unhandled rejections instead of swallowing them.