Issues with Node 25

[dodomorandi]

Describe the bug
The probject experiences strange issues with Node 25. The testing environment throws an assertion and when using happy-dom as a testing environment the localStorage is an empty object.

To Reproduce
Steps to reproduce the behavior in relationship to the project itself:

1. Install and use Node 25 (nvm can be handy)
2. Clone the repo
3. npm install
4. npm run test

Expected behavior
Tests run and pass. This works flawlessly with Node 24.

Screenshots

To Reproduce (2)
Steps to reproduce the (probably related) issue about localStorage from an external project:

1. Install and use Node 25
2. Create a dummy project installing vitest and happy-dom
3. Create the following test file:

   // @vitest-environment happy-dom
   
   import { describe,it } from 'vitest';
   
   describe("test", () => {
     it("breaks localStorage", () => {
       window.localStorage.getItem("hello");
     })
   })

4. Run npx vitest

Expected behavior
Tests run and pass, works with Node 24

Screenshots

Device:

• OS: Arch Linux
• Node 25.1.0

Additional context
I cannot be sure the two noticed behavior are directly correlated, I only supposed so. If you realize the two problems are separated issues just let me know and I will split this specific issue in two.

[brianhelba]

I'm having the same issue.

Note, a warning is also being printed prior to the localStorage.getItem is not a function error:

(node:2282) Warning: --localstorage-file was provided without a valid path
(Use node --trace-warnings ... to show where the warning was created)

---

There's a significant change in Node 25:

Web Storage is enabled by default

[3312e4e946] - (SEMVER-MAJOR) src: unflag --experimental-webstorage by default (Daniel M Brasil) #57666

Looking at the Node docs, it appears that localstorage is now available, but requires the --localstorage-file flag. I'm guessing that Node's localstorage implementation is now taking precedence over Happy DOM's polyfill.

---

I enjoyed the fact that localstorage used to "just work" under Happy DOM. If necessary, I will use Vitest's execArgv config option to pass --localstorage-file into my test suite, but ideally Happy DOM could do this for me on Node 25+.

[brianhelba]

I just found vitest-dev/vitest#8757 , who is punting the issue to upstream Node (which I think is appropriate, though maybe Happy DOM is responsible too).

---

In Node, it looks like v25.2 (released yesterday) contains a fix for nodejs/node#60303 . I just installed v25.2.0 and any access to localstorage now immediately fails with:

SecurityError: Cannot initialize local storage without a --localstorage-file path

This error is also now occurring call to window.localStorage.clear() (which previously didn't fail on v25.1).

---

Per the patch in Node nodejs/node#60351 (comment), it looks like for v25.2+, a downstream needs

function localStorageIsAvailable() {
  try {
    return typeof localStorage !== 'undefined';
  } catch {
    return false;
  }
}

Perhaps Happy DOM can do this, and polyfill window.localstorage with its existing implementation if Node isn't providing it (either because it's not implemented in < v25 or because it's not configured via --localstorage-file).

If we want to get Node v25.0 and v25.1 working, an additional check might be necessary.

[brianhelba]

As a workaround for now, I added to my vitest.config.ts (using Vitest v4):

import os from 'node:os';
import path from 'node:path';
import process from 'node:process';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'happy-dom',
    execArgv: [
      '--localstorage-file',
      path.resolve(os.tmpdir(), `vitest-${process.pid}.localstorage`),
    ],
  },
});

My tests are passing again.