[feature]: The persist middleware provides a configuration to immediately trigger a migration function upon initialization.

[just-ads]

Scene:

1. The project was migrated from other state management libraries (such as Redux-Persist, Vuex, and LocalStorage) to Zustand.

2. The old data is distributed across multiple independent storage keys (e.g., user, settings, cart).

3. After migrating to Zustand, these scattered data need to be read and merged as the initial state of the Zustand store.

Current problem:

On the first load, migrate will not be executed at all, and it will be unable to read data from other keys for merging.

[dai-shi]

The migrate option only works for specific case. If you are migrating from other tools, you may need custom storage.

[mg1986jp]

dai-shi is right — migrate only runs when the same Zustand store's version number changes. It won't fire on the first load if there's no prior Zustand state under that key.

For migrating from Redux-Persist / Vuex / localStorage keys, implement a custom storage that checks the old keys on first read:

import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

const migratingStorage = createJSONStorage(() => localStorage, {
  getItem: (name) => {
    // Check if Zustand already has state under this key
    const existing = localStorage.getItem(name);
    if (existing) return existing;

    // First load — merge from old storage keys
    const oldUser = JSON.parse(localStorage.getItem('user') ?? 'null');
    const oldSettings = JSON.parse(localStorage.getItem('settings') ?? 'null');
    const oldCart = JSON.parse(localStorage.getItem('cart') ?? 'null');

    if (!oldUser && !oldSettings && !oldCart) return null;

    const merged = {
      state: {
        user: oldUser,
        settings: oldSettings,
        cart: oldCart,
      },
      version: 0,
    };

    // Write merged state so this only runs once
    localStorage.setItem(name, JSON.stringify(merged));

    return JSON.stringify(merged);
  },
});

const useAppStore = create(
  persist(
    (set) => ({
      user: null,
      settings: {},
      cart: [],
    }),
    {
      name: 'app-store',
      storage: migratingStorage,
      version: 0,
    }
  )
);

The custom getItem intercepts the first read, checks for old keys, merges them into the Zustand state shape, and writes it back. After that first load, the Zustand key exists and the migration path is skipped.

If your old data needs transformation (different field names, nested structure, etc.), do that in the merge step before writing.

[DaCameraGirl]

The previous comments are on the right track. Here's a complete, copy-pasteable solution.

Why migrate won't work here

Zustand's built-in migrate option only runs when version in persisted state mismatches the store's version number. On first load after migrating from Redux-Persist/Vuex, Zustand finds no persisted state under its own key, so migrate is never called.

Solution: Custom storage with a one-time merge on first read

import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

const OLD_KEYS = {
  user: 'vuex-user',         // old Vuex localStorage key
  settings: 'redux-settings', // old Redux-Persist key
  cart: 'cart',               // old standalone key
};

// One-time migration: read old keys, merge, write to new key, clear old keys
function migrateFromLegacyStorage(newKey: string): void {
  if (localStorage.getItem(newKey)) return; // already migrated

  const user = (() => {
    try { return JSON.parse(localStorage.getItem(OLD_KEYS.user) ?? 'null'); } catch { return null; }
  })();
  const settings = (() => {
    try { return JSON.parse(localStorage.getItem(OLD_KEYS.settings) ?? 'null')?.settings ?? null; } catch { return null; }
  })();
  const cart = (() => {
    try { return JSON.parse(localStorage.getItem(OLD_KEYS.cart) ?? 'null'); } catch { return null; }
  })();

  if (!user && !settings && !cart) return; // nothing to migrate

  // Merge into Zustand's expected persist format
  const mergedState = {
    state: {
      user: user ?? null,
      settings: settings ?? {},
      cart: cart?.items ?? [],
    },
    version: 1,
  };

  localStorage.setItem(newKey, JSON.stringify(mergedState));

  // Clean up old keys
  Object.values(OLD_KEYS).forEach(k => localStorage.removeItem(k));
}

// Run migration before the store initializes
migrateFromLegacyStorage('app-store');

interface AppState {
  user: Record<string, unknown> | null;
  settings: Record<string, unknown>;
  cart: unknown[];
}

export const useAppStore = create<AppState>()(
  persist(
    (_set) => ({
      user: null,
      settings: {},
      cart: [],
    }),
    {
      name: 'app-store',
      version: 1,
      storage: createJSONStorage(() => localStorage),
    }
  )
);

How it works

1. migrateFromLegacyStorage runs synchronously before create() is called
2. It checks if the Zustand key already exists — if yes, migration already happened, skip
3. If not, reads from all old keys, merges them into the Zustand persist format, writes to the new key, and deletes the old keys
4. Zustand's persist middleware then reads the new key normally on store init — it sees valid persisted state and skips the default initialization

Transform old data shapes

If your old data had different field names (e.g. Vuex used currentUser but Zustand uses user), do the transformation in the merge step:

const mergedState = {
  state: {
    user: user?.currentUser ?? null,  // rename field
    settings: {
      theme: settings?.ui?.theme ?? 'light', // remap nested
    },
    cart: cart?.items?.map((i: any) => ({ id: i.product_id, qty: i.quantity })) ?? [],
  },
  version: 1,
};

This approach is a one-time operation — after the first page load under Zustand, the old keys are gone and the migration function becomes a no-op on every subsequent load.

[just-ads]

Thank you everyone, I have solved the migration issue by customizing the storage.