How do I persist Zustand state?

You can use the built-in `persist` middleware. It automatically saves your state to localStorage (default), sessionStorage, or any custom storage engine like AsyncStorage or IndexedDB.

How to fix hydration errors with persist?

Hydration errors occur when the server HTML differs from the client HTML (which has loaded persisted state). To fix this, you can use a custom hook to only return the state after the component has mounted on the client.

Mastering Middleware & Persistence

Learn how to save state to LocalStorage, IndexedDB, and create custom middleware.

Basic Persistence

The `persist` middleware enables you to store your state in a storage (e.g., localStorage, AsyncStorage, IndexedDB, etc.), so that when the user reloads the page, the state is preserved.

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

export const useBearStore = create(
  persist(
    (set, get) => ({
      bears: 0,
      addABear: () => set({ bears: get().bears + 1 }),
    }),
    {
      name: 'food-storage', // name of the item in the storage (must be unique)
      storage: createJSONStorage(() => sessionStorage), // (optional) by default, 'localStorage' is used
    },
  ),
)

Handling Hydration Errors

In Next.js, you might encounter hydration errors because the server renders the initial state (0 bears), but the client hydrates with the persisted state (5 bears).

Solution: Custom Hook

import { useState, useEffect } from 'react'

const useStore = <T, F>(
  store: (callback: (state: T) => unknown) => unknown,
  callback: (state: T) => F,
) => {
  const result = store(callback) as F
  const [data, setData] = useState<F>()

  useEffect(() => {
    setData(result)
  }, [result])

  return data
}

Custom Storage Engines

You can use any storage engine that implements `getItem`, `setItem`, and `removeItem`.

Example: IndexedDB (using idb-keyval)

import { create } from 'zustand'
import { persist, createJSONStorage, StateStorage } from 'zustand/middleware'
import { get, set, del } from 'idb-keyval' // npm install idb-keyval

const storage: StateStorage = {
  getItem: async (name: string): Promise<string | null> => {
    console.log(name, 'has been retrieved')
    return (await get(name)) || null
  },
  setItem: async (name: string, value: string): Promise<void> => {
    console.log(name, 'with value', value, 'has been saved')
    await set(name, value)
  },
  removeItem: async (name: string): Promise<void> => {
    console.log(name, 'has been deleted')
    await del(name)
  },
}

export const useBoundStore = create(
  persist(
    (set, get) => ({
      bears: 0,
      addABear: () => set({ bears: get().bears + 1 }),
    }),
    {
      name: 'food-storage', // unique name
      storage: createJSONStorage(() => storage),
    },
  ),
)