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