Node.js 25: what’s actually new, what broke in the ecosystem, and whether you should upgrade

There are two kinds of Node upgrades. The first is “bump the version, everything works.” The second is “bump the version, and now your backend throws browser-looking errors.” Node.js 25 made a lot of teams experience the second kind.

Docusaurus looked surreal: DOMException [SecurityError]: Cannot initialize local storage without a --localstorage-file path during docusaurus build.[1] Similar symptoms showed up in the CLI world (Shopify) and in test runners (Jest/Vitest).[2][3][4]

This matters: it’s not just “a random bug in your repo.” It’s a consequence of Node 25 enabling Web Storage by default, while Node’s localStorage is not a 1:1 browser storage (file-backed, quota, shared behavior, no encryption).[7][5]

And still: it would be a mistake to reduce Node 25 to the Web Storage saga. 25.4.0 and 25.5.0 shipped genuinely mature improvements (require(esm) stable, compile cache stable, --build-sea) that reduce migration pain and improve DX — if you adopt them deliberately.[9][10][12]

Node 25 is a Current line (odd). It moves fast: first, new defaults land; then the ecosystem finds edge cases; then stabilization releases ship.[6]

Just enough vocabulary to make Node 25 readable.

25.0.0 is the foundation: V8 14.1, performance work, web APIs, and legacy cleanup. The real “maturity” shows up in 25.4/25.5.[8][9][12]

The core issue is not that Web Storage is “bad”. The issue is that the default behavior changed, and parts of toolchains started executing branches they never tested on the server.

nodejs/node #60704 describes the 25.2.0 regression: “Cannot initialize local storage without a --localstorage-file path”. Importantly, it references broken webpack/jest/html-webpack-plugin chains.[5]

Vitest issue #8757 shows another failure mode: in Node 25 localStorage is no longer undefined, which can break mocks in test environments.[4] Jest issue #15888 adds another data point: the test runner fails with the same SecurityError on Node 25.2.0.[3]

Fast incident workaround (when you don’t need storage): temporarily disable Web Storage via the flag documented in Node’s globals docs.[7]

Team lesson: even if “you don’t use localStorage”, your dependencies might. That’s why keeping Current in a CI matrix is a rational way to detect surprises early.[6]

This is the kind of change that doesn’t scream in headlines, but saves weeks in repos where CJS and ESM must coexist.

Compile cache is an optimization. It shines when you have many cold starts or a large module graph (tools, CLIs, workers).

The node:module docs include a very practical portability section: if absolute paths change, cache effectiveness can drop; portable mode helps reuse in more scenarios.[10]

A minimal experiment setup:

import module from 'node:module';

module.enableCompileCache({ directory: '.node-compile-cache', portable: true });

If you test this in CI, manage the cache directory explicitly so it survives between runs.

This is one of the most product-level changes in the line: building a single executable no longer looks like an external-injector ritual.

Not headline features — but they reduce “tiny custom wrappers” in projects with corporate CI constraints.

Minimal snippet:

import http from 'node:http';

const restore = http.setGlobalProxyFromEnv();
// restore();

In large repos, watchers are their own world of pain (node_modules, .git, generated dirs). The docs describe ignore as an option that can take glob/RegExp/function/array.[15]

A minimal example for dev tools:

import { watch } from 'node:fs';

watch('.', {
  recursive: true,
  ignore: ['**/node_modules/**', '**/.git/**'],
}, () => {});

Major Node releases often hurt not via brand-new APIs but via deprecation finalization. SlowBuffer is a clean example.[16]

A short “battle-tested” checklist teams actually use.

No ideology: Node 25 is great as a “future breakage detector” in CI, and it’s useful for certain products (CLIs/agents). But for production backends, LTS often wins on stability alone.

Sources in order of appearance (position in list = footnote number [n]).

The healthiest strategy for most teams: keep prod on LTS, run Node 25 in CI as an early regression detector, and adopt 25.4/25.5 features (require(esm), compile cache, build-sea) first in isolated experiments (CLI/worker). You get the DX upside without “the day localStorage broke the build”.