`docusaurus build` broken with NodeJS 25

[linkdd]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

In Node v25.2.0, simply touching globalThis.localStorage throws unless you pass a storage file, which breaks Docusaurus/SSR if any code references localStorage at build time.

See: vitest-dev/vitest#8757

A workaround is to disable WebStorage during the build:

NODE_OPTIONS="--no-webstorage" docusaurus build

Reproducible demo

No response

Steps to reproduce

With NodeJS 25, run docusaurus build

Expected behavior

localStorage should not be used at build-time.

Actual behavior

This produces the following error:

[ERROR] Error: Unable to build website for locale en.
    at tryToBuildLocale (****/node_modules/@docusaurus/core/lib/commands/build/build.js:83:15)
    at async ****/node_modules/@docusaurus/core/lib/commands/build/build.js:35:9
    at async mapAsyncSequential (****/node_modules/@docusaurus/utils/lib/jsUtils.js:21:24)
    at async Command.build (****/node_modules/@docusaurus/core/lib/commands/build/build.js:34:5)
    at async Promise.all (index 0)
    at async runCLI (****/node_modules/@docusaurus/core/lib/commands/cli.js:56:5)
    at async file://****/node_modules/@docusaurus/core/bin/docusaurus.mjs:44:3 {
  [cause]: DOMException [SecurityError]: Cannot initialize local storage without a `--localstorage-file` path
      at Object.get [as localStorage] (node:internal/webstorage:28:17)
      at get localStorage (node:internal/util:660:20)
      at merge (****/node_modules/eval/eval.js:11:13)
      at module.exports (****/node_modules/eval/eval.js:42:5)
      at ****/node_modules/@docusaurus/core/lib/ssg/ssgRenderer.js:37:108
      at Object.async (****/node_modules/@docusaurus/logger/lib/perfLogger.js:42:47)
      at loadAppRenderer (****/node_modules/@docusaurus/core/lib/ssg/ssgRenderer.js:37:51)
      at async Promise.all (index 0)
      at async loadSSGRenderer (****/node_modules/@docusaurus/core/lib/ssg/ssgRenderer.js:53:54)
      at async executeSSGInlineTask (****/node_modules/@docusaurus/core/lib/ssg/ssgWorkerInline.js:13:25)
}
[INFO] Docusaurus version: 3.9.2
Node version: v25.2.0

Your environment

• Docusaurus version used: 3.9.2
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node.js 25.2.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Ubuntu 25.04

Self-service

• I'd be willing to fix this bug myself.

[slorber]

Thanks for reporting, will investigate later but this seems related to this change nodejs/node#60351

[brianhelba]

Workaround: capricorn86/happy-dom#1950 (comment)

[slorber]

We'll see if Node is going to revert that change: nodejs/node#60704

In the meantime, it's preferable you keep using Node < 25.2 because we don't have any fix we can quickly release.

It doesn't just break Docusaurus SSG (I'll look into fixing it asap), but also a third-party dependency used in our dev server: jantimon/html-webpack-plugin#1880

[slorber]

For our SSG process, this breaks the "eval" npm lib we use due to merging global into another object: https://github.com/pierrec/node-eval/blob/master/eval.js

Unfortunately, that lib is archived, so unless node reverts, we'd have to fork/internalize it.

[slorber]

Going to close this issue for now because:

• They reverted the breaking change in v25.2.1
• That breaking change may not land in v26, see localStorage's behaviour when no or invalid --localstorage-file provided nodejs/node#60303 (comment)

We'll re-open for v26 if they still plan to ship that breaking change