Node 25 - Zustand persist blows up in node 25

[Nick2bad4u]

Bug Description

Zustand persist breaks with Node 25’s new web storage stub

Summary

Running stores wrapped in persist now explodes with:

TypeError: storage.setItem is not a function

under Node.js 25 whenever the process receives --localstorage-file without a valid path.

Node 25 auto-initializes a bare {} at globalThis.localStorage in that configuration; the persist middleware trusts localStorage blindly and calls setItem → immediate crash.

Environment

• Node.js 25.0.0 (Windows 11 x64 tested, but this is runtime-level and OS-agnostic)
• Zustand 5.0.8 (zustand/middleware → persist)
• Reproduced in Vitest 3.2.4 and by running the snippet directly with node

Minimal Repro

1. Ensure NODE_OPTIONS contains --localstorage-file without a path (VS Code’s JS debug bootloader does this automatically, but you can set it yourself).
2. Create repro.mjs:

import { createStore } from "zustand/vanilla";
import { persist } from "zustand/middleware";

const useStore = createStore(
  persist(
    () => ({ count: 0 }),
    { name: "counter" }
  )
);

console.log(useStore.getState().count);

3. Run with Node 25:

$env:NODE_OPTIONS='--localstorage-file'
node repro.mjs

4. Observe crash:

TypeError: storage.setItem is not a function
    at setItem (node_modules/zustand/esm/middleware.mjs:297:22)
    …

Expected

If getStorage() hands back something that doesn’t actually behave like Web Storage, persist should notice. It should either fall back to an in-memory store or throw a specific, helpful error. The one thing it must not do is blindly call .setItem() on a value whose methods haven’t been verified.

Actual

Under Node 25, localStorage resolves to a plain {}. persist skips validation, calls .setItem, and the store crashes immediately. Any persisted store-tests, scripts, production-dies the moment it initializes.

Why It Matters

The --localstorage-file flag is now common (VS Code’s debugger sets it automatically), so this configuration isn’t exotic. Without a fix, every Zustand project that upgrades to Node 25 hits a fatal error unless they add custom shims.

Reproduction Link

I put one in the bug report

[dai-shi]

Thanks for reporting! What's your idea for the fix?

[Nick2bad4u]

Thanks for reporting! What's your idea for the fix?

I built my own custom web storage shim in the mean time to get my tests working.

Works fine, but I'm not sure it'll work for everyone.

I'm not super familiar with this codebase.

[SheldonWBM]

What is the custom web storage shim? Do you have sample code?

[Nick2bad4u]

What is the custom web storage shim? Do you have sample code?

Not sure if it'll work for everyone:

https://github.com/Nick2bad4u/Uptime-Watcher/blob/main/src%2Ftest%2Fsetup.ts#L133-L238

/**
 * Minimal Web Storage implementation used when Node.js exposes an incomplete
 * `localStorage` or `sessionStorage` shim via experimental flags.
 */
interface StorageShim {
    readonly length: number;
    clear: () => void;
    getItem: (key: string) => string | null;
    key: (index: number) => string | null;
    removeItem: (key: string) => void;
    setItem: (key: string, value: string) => void;
}

/**
 * Supported storage keys that require reliable mocks during tests.
 */
type StorageKey = "localStorage" | "sessionStorage";

/**
 * Storage methods that must exist on a usable Web Storage implementation.
 */
const STORAGE_METHODS: readonly (keyof StorageShim)[] = [
    "clear",
    "getItem",
    "key",
    "removeItem",
    "setItem",
];

/**
 * Creates an in-memory Map-backed storage implementation matching the Web
 * Storage API used by browsers.
 */
const createStorageShim = (): StorageShim => {
    const storage = new Map<string, string>();

    return {
        get length(): number {
            return storage.size;
        },
        clear(): void {
            storage.clear();
        },
        getItem(key: string): string | null {
            return storage.has(key) ? (storage.get(key) ?? null) : null;
        },
        key(index: number): string | null {
            return Array.from(storage.keys())[index] ?? null;
        },
        removeItem(key: string): void {
            storage.delete(key);
        },
        setItem(key: string, value: string): void {
            storage.set(key, String(value));
        },
    } satisfies StorageShim;
};

/**
 * Determines whether the provided value already implements the Web Storage API
 * surface that our tests rely on.
 */
const hasValidStorage = (candidate: unknown): candidate is StorageShim => {
    if (candidate === null || typeof candidate !== "object") {
        return false;
    }

    const descriptor = Reflect.getOwnPropertyDescriptor(candidate, "length");
    const lengthValue = (candidate as { length?: unknown }).length;
    const hasLength =
        typeof lengthValue === "number" ||
        (typeof descriptor?.get === "function" &&
            typeof descriptor.get.call(candidate) === "number");

    if (!hasLength) {
        return false;
    }

    return STORAGE_METHODS.every(
        (method) =>
            typeof (candidate as Record<string, unknown>)[method] === "function"
    );
};

/**
 * Ensures `globalThis` exposes a fully functional storage implementation under
 * the given key, overriding Node's placeholder when necessary.
 */
const ensureStorage = (storageKey: StorageKey): void => {
    const existing = Reflect.get(globalThis, storageKey) as unknown;

    if (hasValidStorage(existing)) {
        return;
    }

    Object.defineProperty(globalThis, storageKey, {
        configurable: true,
        enumerable: true,
        value: createStorageShim(),
        writable: true,
    });
};

ensureStorage("localStorage");
ensureStorage("sessionStorage");

[SheldonWBM]

The shim works for me, thank you :)

I added to setupFiles: ['vitests/storageShim.ts', 'vitests/setup.ts'], in my vite.config to ensure the storageShim is imported first.

I added the below to my implementation of the storage shim

/**
 * Suppress Node.js warning about --localstorage-file flag without valid path.
 * This warning is harmless since our shim provides a complete implementation.
 */
const originalEmitWarning = process.emitWarning.bind(process);
type ArgsType = [warning: string | Error];
process.emitWarning = ((...args: ArgsType) => {
  const warning = args[0];
  // Filter out the localstorage-file warning
  const warningText = typeof warning === 'string' ? warning : warning?.message;
  if (
    typeof warningText === 'string' &&
    warningText.includes('--localstorage-file') &&
    warningText.includes('was provided without a valid path')
  ) {
    return;
  }
  // Pass through all other warnings
  originalEmitWarning(...args);
}) as typeof process.emitWarning;

[Nick2bad4u]

The shim works for me, thank you :)

I added to setupFiles: ['vitests/storageShim.ts', 'vitests/setup.ts'], in my vite.config to ensure the storageShim is imported first.

I added the below to my implementation of the storage shim

/**
 * Suppress Node.js warning about --localstorage-file flag without valid path.
 * This warning is harmless since our shim provides a complete implementation.
 */
const originalEmitWarning = process.emitWarning.bind(process);
type ArgsType = [warning: string | Error];
process.emitWarning = ((...args: ArgsType) => {
  const warning = args[0];
  // Filter out the localstorage-file warning
  const warningText = typeof warning === 'string' ? warning : warning?.message;
  if (
    typeof warningText === 'string' &&
    warningText.includes('--localstorage-file') &&
    warningText.includes('was provided without a valid path')
  ) {
    return;
  }
  // Pass through all other warnings
  originalEmitWarning(...args);
}) as typeof process.emitWarning;

You can also just import the shim at the top of the setup.ts file and then not have to worry about config changes.

That's how I did it at least.

[dbritto-dev]

tbh, that's a expected behavior for this case you need to create a custom storage or mock localStorage

[Nick2bad4u]

True. But now every single person with vscode and or node25 will need a custom shim

[honuuk]

Hi @dbritto-dev

I agree that providing a custom storage (or mocking localStorage) is the correct approach in Node environments.

While looking into this, I noticed that createJSONStorage already treats storage as “optional” — if getStorage throws, it silently returns undefined and persist becomes a no-op (similar to SSR).

Given that, I was wondering whether it would make sense to also treat invalid storages (e.g. objects that don’t implement the StateStorage interface, like {} from Node’s experimental localStorage shim) in the same way.

Right now, getStorage succeeds, but setItem later throws at runtime. Conceptually, it feels closer to the “storage unavailable” case, where persist is intentionally ignored.

Not suggesting a change in behavior for Node usage per se — but would it make sense to consider a small guardrail so the runtime behavior better aligns with the existing intent of createJSONStorage?

[dbritto-dev]

@honuuk create createJSONStorage wasn't created to be safe by default that's why we encourage developers to create their own custom storage, you can have the same behavior using localeStorage directly.

Ref: https://zustand.docs.pmnd.rs/integrations/persisting-store-data#how-can-i-use-a-custom-storage-engine

[dai-shi]

Should we check .setItem?

storage = getStorage()
if (!storage.setItem) {
  throw new Error('Storage does not have setItem method');
}

[dbritto-dev]

That wouldn't work on non-browser environments

[dai-shi]

It's within a try-catch block. Or, is it a different concern?

[honuuk]

@dai-shi @dbritto-dev
What I initially had in mind was removing the try-catch block and throwing an explicit error when an invalid storage is provided.
However, since the default storage in persistImpl is localStorage, I can see why that approach might be tricky.

The exact solution still needs some thought, but my main concern is around cases where localStorage resolves to something invalid like {}, or where a custom storage is provided but doesn’t actually behave like a proper storage.

For example, something like this currently fails at runtime:

import { createStore } from 'zustand/vanilla'
import { createJSONStorage, persist } from 'zustand/middleware'

const useStore = createStore(
  persist(() => ({ count: 0 }), {
    name: 'counter',
    storage: () => ({}),
  })
)

console.log(useStore.getState().count)

The goal here isn’t to eliminate runtime errors, but to surface a more explicit and intentional error when the storage is invalid, rather than failing later in a less clear way.

Curious to hear your thoughts — if this direction makes sense, I’m happy to explore possible approaches.

[dai-shi]

We don't prefer runtime solutions. This should be checked through types.
I think window.localStorage will work for the most cases.

[honuuk]

I’ve opened a small PR(#3367) based on this discussion, updating the default storage reference to window.localStorage.
Just sharing it here for context.