React Academy · Lesson

Persisting State with the Persist Middleware

Sync Zustand state to localStorage or sessionStorage using the persist middleware.

Persisting State with the Persist Middleware is a free React Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the React Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Welcome

In this lesson you will use Zustand's persist middleware to automatically sync store state to localStorage so it survives page reloads.

Why Persist State?

Without persistence, all store state resets when the user refreshes the page. Persisting stores like cart items, user preferences, or UI state (open panels) to localStorage gives users a seamless experience across sessions.

The persist Middleware

Wrap your create() call with persist(). Provide a unique storage key. Zustand will automatically read from localStorage on mount and write on every state change.

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

const useCartStore = create(
  persist(
    (set) => ({
      items: [],
      addItem: (item) => set(s => ({ items: [...s.items, item] })),
    }),
    { name: 'cart-storage' } // localStorage key
  )
);

Partial Persistence with partialize

Use `partialize` to persist only specific slices of the store. This excludes transient data (like loading flags) from localStorage.

persist(
  (set) => ({ user: null, token: null, loading: false, fetch: () => {} }),
  {
    name: 'auth-storage',
    partialize: (state) => ({ user: state.user, token: state.token }),
    // loading and fetch are NOT persisted
  }
)

Using sessionStorage

To persist for the browser session only (cleared on tab close), pass `createJSONStorage(() => sessionStorage)` as the storage option.

import { createJSONStorage } from 'zustand/middleware';

persist(storeCreator, {
  name: 'session-data',
  storage: createJSONStorage(() => sessionStorage),
})

Versioning and Migration

When your store shape changes (new fields, renamed keys), set a `version` number and provide a `migrate` function to upgrade old persisted data.

persist(storeCreator, {
  name: 'my-store',
  version: 2,
  migrate: (persistedState, version) => {
    if (version === 1) {
      return { ...persistedState, newField: 'default' };
    }
    return persistedState;
  },
})

Hydration and SSR

On the server (Next.js), localStorage does not exist. Zustand's persist middleware handles this gracefully — it skips hydration on the server and rehydrates on the client after mount.

onRehydrateStorage Callback

Use `onRehydrateStorage` to run code when the store is restored from storage. Useful for triggering an API call after restoring a token.

persist(storeCreator, {
  name: 'auth',
  onRehydrateStorage: () => (state) => {
    if (state?.token) state.fetchUser();
  },
})

Clearing Persisted State

Call `useMyStore.persist.clearStorage()` to remove the persisted data from localStorage — useful for logout flows.

const handleLogout = () => {
  useAuthStore.persist.clearStorage();
  useAuthStore.setState({ user: null, token: null });
};

Storage Size Limits

localStorage has a 5–10 MB limit per origin. Avoid persisting large data sets (e.g. full product catalogs). Persist only identifiers or small configuration objects.

Quick Check

What option in the persist middleware lets you exclude certain state fields from being saved to localStorage?

Recap

Wrap your Zustand store with persist() and provide a name key. Use partialize to store only relevant slices. Version and migrate when the store shape changes. Use clearStorage() on logout.

Up Next

Next lesson: **Zustand DevTools & Testing Stores** — you will connect to Redux DevTools and write unit tests for Zustand actions.

Frequently asked questions

Is the “Persisting State with the Persist Middleware” lesson free?

Yes — the full text of “Persisting State with the Persist Middleware” is free to read here on the web, and the React Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the React Academy course, upgrade to CoddyKit PRO.

What will I learn in “Persisting State with the Persist Middleware”?

Sync Zustand state to localStorage or sessionStorage using the persist middleware. You practise React Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start React Academy?

No prior experience is required. React Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Persisting State with the Persist Middleware” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this React Academy lesson?

Yes. Every React Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Creating Your First Zustand Store
Selectors & Preventing Unnecessary Re-renders
Persisting State with the Persist Middleware
Zustand DevTools & Testing Stores

← Back to React Academy