Zustand Persist Middleware: Managing State Migrations via the Version Property

Sequential Migration in Zustand

Zustand's persist middleware does not provide a built-in mechanism to automatically iterate through intermediate versions. The migrate function is invoked exactly once during the hydration process. It receives the persisted state and the version number stored in that state, but it is the developer's responsibility to transform that state into the current schema.

To prevent data loss when a user skips multiple application updates, you must manually implement a version-checking loop within the migrate callback to ensure transformations are applied sequentially.

Implementation Pattern for Multi-Step Transitions

The most reliable approach is to define a set of migration functions and execute them in a while loop until the persisted version matches the current store version.

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

const migrations = {
  0: (state) => ({ ...state, newField: 'default' }), // v0 to v1
  1: (state) => ({ ...state, newField: state.newField.toUpperCase() }), // v1 to v2
  2: (state) => ({ ...state, otherField: true }), // v2 to v3
};

const useStore = create(
  persist(
    (set) => ({ 
      /* state */ 
    }),
    {
      name: 'app-storage',
      version: 3, // Current version
      migrate: (persistedState, version) => {
        let currentState = persistedState;
        let currentVersion = version;

        while (currentVersion < 3) {
          const migrationFn = migrations[currentVersion];
          if (migrationFn) {
            currentState = migrationFn(currentState);
            currentVersion++;
          } else {
            // Break loop if a version is missing to avoid infinite loops
            break;
          }
        }
        return currentState;
      },
    },
  )
);

Technical Considerations

• Synchronous Execution: The migrate function should remain synchronous. Because hydration occurs during store initialization, asynchronous logic can lead to race conditions or inconsistent UI states before the store is ready.
• Idempotency: Ensure each migration function is idempotent. If a migration is interrupted or re-run, it should not corrupt the state.
• Version Mapping: Using an object lookup (as shown above) is generally more maintainable than a large switch statement as the number of versions grows.

Verification Steps

To verify your migration logic, you can manually seed your local storage with an outdated version number and state object:

1. Open the browser console and manually set a legacy state: localStorage.setItem('app-storage', JSON.stringify({ state: { oldKey: 'val' }, version: 0 })).
2. Reload the application.
3. Inspect the store state to confirm that all intermediate transformations (v0 → v1 → v2 → v3) were applied in the correct order.