- The
enginesfield inpackage.json, and.nvmrcor.node-version - The lockfile, which names the package manager (
package-lock.json,pnpm-lock.yaml,yarn.lock, orbun.lock) - The
typefield, which decides between ESM and CommonJS - The test runner, framework, logger, and validation library already in
package.json
Use an API only when the project's Node.js version has it. node-lts.md lists the supported lines and what each one added or removed. A library recommended here, such as pino or close-with-grace, is a default for new code. A new dependency still needs the user's request or the repository's practice for this kind of change, as code_rules says.
import type { IncomingMessage } from 'node:http';
const greet = (name: string): string => `Hello, ${name}!`;
console.log(greet('world'));
references/typescript.md has the full rules and the tsconfig.
- Graceful shutdown registers handlers for
SIGTERMandSIGINTand stops accepting new work. It then drains in-flight requests, closes external connections such as the database and cache, and exits with the right code. See references/graceful-shutdown.md. - Error handling classifies errors by code and keeps the
causechain. It leaves process-level handlers to close-with-grace when the project has it and logs context before it responds or crashes. See references/error-handling.md. - A flaky test needs its cause found. Isolate the test, check shared state and timer dependencies, and inspect the async teardown order. A retry or a longer timeout hides the fault, so fix the cause instead. See references/flaky-tests.md.
- A stuck process or test run needs its open handles found. Isolate the file and test, run with an explicit timeout and reporter, and inspect the handles with
why-is-node-running. Then fix the teardown where the resource is created and rerun until stable. See references/stuck-processes-and-tests.md. - A slow path needs a profile. Reproduce it under realistic load and capture a CPU profile with flame or
--cpu-prof. Find the hot functions, check for backpressure problems or needless serialization, and measure the fix with a benchmark. See references/profiling.md and references/performance.md.
- Use
await pipeline(...)fromnode:stream/promisesinstead of chained.pipe(). - Use an
async function*transform when the existing stream stages cannot express the required transformation simply. - Consider a cache when repeated work causes a measured problem and the freshness requirements allow reuse.
lru-cachefits bounded in-memory reuse in one process.async-cache-dedupefits async request deduplication and stale-while-revalidate. Followcode_rulesbefore adding either dependency. - Handle backpressure through
pipeline()or through an explicitdrainwait.
For large CSV or ETL inputs, createReadStream(input) and await pipeline(...) keep memory bounded. Reuse the existing parser and add enrichment or caching only when the task needs them. references/streams.md and references/caching.md have the details.
- references/async-patterns.md before you write async/await code, run work in parallel, limit concurrency, or cancel work.
- references/error-handling.md before you throw, catch, classify, or log an error, including async errors.
- references/streams.md before you build a pipeline, a transform, or a stream consumer, or handle backpressure.
- references/modules.md before you choose between ESM and CommonJS, use
require(esm), or change import paths. - references/testing.md before you write or change tests with
node:test, mocks, snapshots, or hooks. - references/flaky-tests.md when a test passes and fails without a code change.
- references/stuck-processes-and-tests.md when a process or test run never exits.
- references/node-modules-exploration.md before you look up installed versions, dependency trees, or package internals.
- references/performance.md when the event loop blocks, or before you add worker threads, pools, or hunt a leak.
- references/caching.md before you add a cache or change how one is invalidated.
- references/profiling.md before you profile, benchmark, or take a diagnostic report.
- references/logging.md before you add or change logging, redaction, or debug output.
- references/environment.md before you read env files, validate config, or handle secrets.
- references/graceful-shutdown.md before you handle signals, shut a server down, or add a health check.
- references/typescript.md before you run TypeScript in Node.js, write its tsconfig, or publish a TypeScript package.
- node-lts.md before you rely on a Node.js API that depends on the version, or upgrade Node.js.