Node.js

Release Lines, Pinning, and What a Major Upgrade Actually Breaks

Node publishes a new major every six months. Even-numbered majors arrive in April and become Long Term Support that October, then get roughly thirty months from first release before they go end of life. Odd-numbered majors arrive in October and are supported for about six months; they exist to land breaking changes, not to carry production traffic. End of life means no security patches, not merely no new features, so a service that stays on a line past that date is running unpatched whether or not anyone has noticed.

What breaks on a major upgrade is usually not your JavaScript. Native addons compiled against V8's ABI carry a NODE_MODULE_VERSION and have to be rebuilt for each major, so a package with no prebuilt binary for the new version either compiles from source on the build machine or fails outright; addons written against Node-API are the exception, because that ABI is stable across majors. A major can also bring a new bundled OpenSSL, and OpenSSL 3 moved older algorithms into a legacy provider that is not loaded by default, so code that reads an old PKCS#12 bundle or asks for a retired cipher returns an unsupported-algorithm error rather than a wrong answer. The engines field in package.json records the intended range, but npm treats it as advisory unless engine-strict is set, so the version that actually runs is whatever the image or the host provides.

Upgrades also subtract work. fetch is a global from Node 18, a test runner ships as node:test, --watch restarts the process on file changes, and --env-file reads a .env file, all of which used to arrive as packages. When you move a release line, check whether something in the manifest is now redundant.

The Module Boundary: ESM, CommonJS, and Interop

Node runs two module systems in the same process tree. The type field in package.json decides how .js files are read, module for ESM and commonjs or nothing for CommonJS, while .mjs and .cjs are always one or the other regardless of that setting. ESM is resolved and evaluated asynchronously, which is why CommonJS could not require() an ES module for years and produced ERR_REQUIRE_ESM instead; newer release lines allow require() of an ES module graph that contains no top-level await, and dynamic import() remains the escape hatch that works from either side. The direction that always worked is ESM importing CommonJS, though named imports from a CommonJS file are recovered by static analysis of the source and fall back to a default-only import when exports are assigned in a loop or behind a condition.

The failure modes are specific and worth recognizing on sight. In ESM there is no __dirname, no __filename and no require; the replacements are import.meta.url with fileURLToPath, and import.meta.dirname on newer runtimes. Relative specifiers must carry their file extension, which is why TypeScript source targeting ESM has to import "./thing.js" for a file named thing.ts, and why leaving it off produces ERR_MODULE_NOT_FOUND only after the build. When a dependency adds an exports map to its package.json, deep imports into its internals start throwing ERR_PACKAGE_PATH_NOT_EXPORTED, and the repair is to move to the public entry point rather than to pin around it.

For a new service, choose one system and record it in package.json before the first dependency lands. Mixed graphs work, but the cost shows up in tooling configuration, where the test runner, the transpiler and the bundler each have to be told the same thing again, and in every developer who has to keep track of which half of the codebase they are editing.

One Thread per Process, and the Pool Behind It

A Node process runs your JavaScript on a single thread, so capacity beyond one core comes from running several processes: the cluster module, a process manager, or container replicas with something in front distributing connections. The consequence that gets missed is that anything held in a variable is per-process. An in-memory cache is warmed separately in each one and can hold different answers, a rate limiter counts to its limit once per process, and a scheduler started inside the application fires once per process rather than once per deployment. Each of those has to move to shared storage, a lock, or an external scheduler, and until it does the symptom is intermittent behavior that depends on which process happened to take the request.

Behind the single thread, libuv keeps a small pool of worker threads that a few standard library operations depend on: file system calls, zlib compression, some crypto functions such as pbkdf2 and scrypt, and dns.lookup, which is what a hostname in an outbound HTTP request resolves through unless the code calls dns.resolve directly. The pool defaults to four threads. Saturating it produces latency on exactly those operations while CPU stays low and the event loop shows no delay, so one slow DNS server can occupy every slot while the process looks idle. UV_THREADPOOL_SIZE is the adjustment.

Telling Apart the Three Reasons a Node Service Is Slow

Slow requests in a Node service almost always trace to one of three causes: the event loop is blocked, the service is waiting on something downstream, or requests are queueing for a limited resource. On a latency chart the three are indistinguishable. What separates them is which signals move together, so the triage is to read process CPU, event loop delay, and the service's own recorded timings for its outbound calls at the same moment rather than one at a time.

• Blocked event loop. CPU on the process is high, event loop delay measured with perf_hooks monitorEventLoopDelay climbs into the tens or hundreds of milliseconds, and every endpoint slows together, including ones that touch nothing, such as a health check. Get the work off the thread; adding replicas raises total throughput but leaves every request queued behind the blocking one on its own process.
• Waiting downstream. CPU is low, event loop delay is flat, and your latency tracks a database query or an upstream API almost exactly. The fix belongs to that query or that service, and adding replicas puts more load on whatever is already slow.
• Queueing for a resource. Time is spent before the work starts, visible as connection pool acquire time, threadpool waits, or an outbound agent sitting at its socket limit, while the downstream reports normal timings and latency rises in steps as concurrency grows. Raise the limit or lower concurrency, and count the pool across every process and replica against the database server's own maximum.

Timeouts, Keep-Alive, and Stopping Without Dropping Requests

Node's HTTP server ships defaults chosen for a server facing the open internet, not one sitting behind a proxy. server.keepAliveTimeout is five seconds; if the load balancer's idle timeout is longer, the proxy will eventually reuse a connection at the moment Node is closing it, and the result is a low, steady rate of 502s that no application log explains. Set keepAliveTimeout above the proxy's idle timeout and keep headersTimeout above keepAliveTimeout, and treat the two as one setting with two numbers. server.requestTimeout defaults to five minutes, which is a ceiling rather than a service level.

Outbound, the defaults run the other way. A request made with fetch has no overall deadline, so a call to a service that accepts the connection and then stalls can outlive the request budget of the caller waiting on you. AbortSignal.timeout() is how you impose one, and the value has to be smaller than the timeout your own caller is holding, or the deadline is decorative.

Shutdown is the part that gets written last and tested least. On SIGTERM, server.close() stops accepting new connections but leaves idle keep-alive connections open until they expire on their own, which is what closeIdleConnections() is for, and an orchestrator that follows SIGTERM with SIGKILL after a grace period will cut off anything still running. The ordering that avoids dropped requests is to fail the readiness probe first, allow the load balancer time to stop routing, then close the server and let in-flight work finish. Note also that since Node 15 an unhandled promise rejection terminates the process by default, so a missing catch is a restart and the supervisor's restart policy is part of the design.