`localStorage`'s behaviour when no or invalid `--localstorage-file` provided

[Renegade334]

Prior to #57666, accessing the global localStorage would throw an error if --localstorage-file was invalid at the point of lazy initialisation.

Now, it provides an empty proxy object which responds undefined to all property access. This is neither spec-compliant nor straightforwardly observable.

Looking at the PR, it seems like this was an attempt to avoid throwing warnings in the test suite if simply testing for the presence of the global variable. It seems to me like the better approach would be for the tests to be changed (eg. by checking for the flag instead), and for the implementation to be kept sane.

A couple of options would be:

• Implement mcollina's original proposal, and have the getter warn and return undefined if the storage cannot be initialised.
• The localStorage global getter is allowed to throw a DOMException in the spec if the storage cannot be safely initialised, which is more abrupt, but arguably more consistent with the web.

[ssalbdivad]

I believe this is breaking ArkType's CI for node 25:

https://github.com/arktypeio/arktype/actions/runs/18625450435/job/53103115467?pr=1522

[odewdney]

how can we silently test for a working localStorage? it used to be a test for a defined localStorage in a try block, now that returns true, but if we try to access localStorage, it prints a warning to the console. and now we also need to test for eg localStorage.getItem is defined to see if its a real implementation.

why make the object available if there is no file supplied to back it.

[inoyakaigor]

Just updateted onto 25 and got an error in my test cases because of localstorage.getItem is undefined.
Here is some BaseApiService which is just layer above axios.
A code is:

If I set flag --no-webstorage everything works fine – getItem is exists:

But if I run tests as usual, I get an error because of this:

[inoyakaigor]

@danielmbrasil because of you implemented this changes could you please have a look into this problem? Thank you in advance!

[ssalbdivad]

In case anyone is looking for a workaround, I'm currently using this:

// workaround for a bug in Node 25 that creates localStorage as an empty proxy,
// leading to @typescript/vfs eventually throwing when it sees that it is not
// undefined and tries to call `getItem`:

// https://github.com/nodejs/node/issues/60303

// this can be removed once the bug is addressed in Node
if (!globalThis.localStorage.getItem)
	globalThis.localStorage = undefined as never

[JakobJingleheimer]

I think should be the second option: throw on failed initialisation.

[RafaelGSS]

Throw on failed initialization seems a follow-up semver-major PR. I'd first add a warning starting on v25, and on v26 throw the DOM Exception.

cc: @mcollina @cjihrig wdyt?

[Renegade334]

Throw on failed initialization seems a follow-up semver-major PR.

Note that the implementation is still marked as unstable, so this isn't necessarily mandatory.

[mcollina]

@RafaelGSS, we should fix this how we think it's best. It's experimental and iterate on it until v26.

[mcollina]

Implement #57666 (comment), and have the getter warn and return undefined if the storage cannot be initialised.

I second this.

[RafaelGSS]

We had a brief discussion at the release channel, and it seems we are going to release v25.1.0 without this patch (@aduh95 doesn't have bandwidth to postpone the release), and I can work on v25.2.0 with this patch (throwing the error).

cc: @nodejs/releasers

[cjihrig]

@RafaelGSS that SGTM.

[JakobJingleheimer]

@RafaelGSS do you mean 25.1.0 and 25.2.0?

[RafaelGSS]

Yes. Just updated.