Zustand State Management

Zustand State Management

Status: Production Ready ✅ Last Updated: 2025-11-21 Latest Version: zustand@5.0.8 Dependencies: React 18+, TypeScript 5+

---

Quick Start (3 Minutes)

1. Install Zustand

bun add zustand  # preferred
# or: npm install zustand
# or: yarn add zustand

Why Zustand?

• Minimal API: Only 1 function to learn (create)
• No boilerplate: No providers, reducers, or actions
• TypeScript-first: Excellent type inference
• Fast: Fine-grained subscriptions prevent unnecessary re-renders
• Flexible: Middleware for persistence, devtools, and more

2. Create Your First Store (TypeScript)

import { create } from 'zustand'

interface BearStore {
  bears: number
  increase: (by: number) => void
  reset: () => void
}

const useBearStore = create<BearStore>()((set) => ({
  bears: 0,
  increase: (by) => set((state) => ({ bears: state.bears + by })),
  reset: () => set({ bears: 0 }),
}))

CRITICAL: Notice the double parentheses create<T>()() - this is required for TypeScript with middleware.

3. Use Store in Components

import { useBearStore } from './store'

function BearCounter() {
  const bears = useBearStore((state) => state.bears)
  return <h1>{bears} around here...</h1>
}

function Controls() {
  const increase = useBearStore((state) => state.increase)
  return <button onClick={() => increase(1)}>Add bear</button>
}

Why this works:

• Components only re-render when their selected state changes
• No Context providers needed
• Selector function extracts specific state slice

---

The 3-Pattern Setup Process

Pattern 1: Basic Store (JavaScript)

For simple use cases without TypeScript:

import { create } from 'zustand'

const useStore = create((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
}))

When to use:

• Prototyping
• Small apps
• No TypeScript in project

Pattern 2: TypeScript Store (Recommended)

For production apps with type safety:

import { create } from 'zustand'

// Define store interface
interface CounterStore {
  count: number
  increment: () => void
  decrement: () => void
}

// Create typed store
const useCounterStore = create<CounterStore>()((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
}))

Key Points:

• Separate interface for state + actions
• Use create<T>()() syntax (currying for middleware)
• Full IDE autocomplete and type checking

Pattern 3: Persistent Store

For state that survives page reloads:

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

interface UserPreferences {
  theme: 'light' | 'dark' | 'system'
  language: string
  setTheme: (theme: UserPreferences['theme']) => void
  setLanguage: (language: string) => void
}

const usePreferencesStore = create<UserPreferences>()(
  persist(
    (set) => ({
      theme: 'system',
      language: 'en',
      setTheme: (theme) => set({ theme }),
      setLanguage: (language) => set({ language }),
    }),
    {
      name: 'user-preferences', // unique name in localStorage
      storage: createJSONStorage(() => localStorage), // optional: defaults to localStorage
    },
  ),
)

Why this matters:

• State automatically saved to localStorage
• Restored on page reload
• Works with sessionStorage too
• Handles serialization automatically

---

Critical Rules

Always Do

✅ Use create<T>()() (double parentheses) in TypeScript for middleware compatibility ✅ Define separate interfaces for state and actions ✅ Use selector functions to extract specific state slices ✅ Use set with updater functions for derived state: set((state) => ({ count: state.count + 1 })) ✅ Use unique names for persist middleware storage keys ✅ Handle Next.js hydration with hasHydrated flag pattern ✅ Use shallow for selecting multiple values ✅ Keep actions pure (no side effects except state updates)

Never Do

❌ Use create<T>(...) (single parentheses) in TypeScript - breaks middleware types ❌ Mutate state directly: set((state) => { state.count++; return state }) - use immutable updates ❌ Create new objects in selectors: useStore((state) => ({ a: state.a })) - causes infinite renders ❌ Use same storage name for multiple stores - causes data collisions ❌ Access localStorage during SSR without hydration check ❌ Use Zustand for server state - use TanStack Query instead ❌ Export store instance directly - always export the hook

---

Known Issues Prevention (5 Issues)

Most Critical - TypeScript double parentheses:

// ❌ WRONG: create<T>((set) => ...)
// ✅ CORRECT: create<T>()((set) => ...)

See: references/known-issues.md for complete solutions with code examples.

---

Middleware Configuration

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

const useStore = create<MyStore>()(
  devtools(
    persist(
      (set) => ({ /* store definition */ }),
      { name: 'my-storage' },
    ),
    { name: 'MyStore' },
  ),
)

Order matters: devtools(persist(...)) shows persist actions in DevTools.

See: references/middleware-guide.md for complete middleware documentation.

---

Common Patterns

See: references/common-patterns.md for complete implementations.

---

Advanced Topics

See: references/advanced-topics.md for complete implementations.

---

Bundled Resources

---

When to Load References

---

Quick Troubleshooting

---

Dependencies

{ "dependencies": { "zustand": "^5.0.8", "react": "^18.0.0+" } }

Compatibility: React 18+, React 19, TypeScript 5+, Next.js 14+, Vite 5+

---

Official Docs: https://zustand.docs.pmnd.rs/ | GitHub: https://github.com/pmndrs/zustand

Advanced Zustand Topics

This reference covers advanced Zustand patterns for complex use cases.

---

Vanilla Store (Without React)

Use Zustand outside React for Node.js, tests, or framework-agnostic code.

import { createStore } from 'zustand/vanilla'

interface CounterStore {
  count: number
  increment: () => void
  decrement: () => void
}

const store = createStore<CounterStore>()((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
}))

// Subscribe to changes
const unsubscribe = store.subscribe((state, prevState) => {
  console.log('Count changed:', prevState.count, '->', state.count)
})

// Get current state
console.log(store.getState().count) // 0

// Update state
store.getState().increment()
console.log(store.getState().count) // 1

// Direct set
store.setState({ count: 10 })

// Cleanup
unsubscribe()

Using Vanilla Store in React

import { createStore, useStore } from 'zustand'

// Create vanilla store
const counterStore = createStore<CounterStore>()((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}))

// Create React hook
function useCounterStore<T>(selector: (state: CounterStore) => T): T {
  return useStore(counterStore, selector)
}

// Use in component
function Counter() {
  const count = useCounterStore((state) => state.count)
  return <div>{count}</div>
}

---

Custom Middleware

Create reusable middleware for cross-cutting concerns.

Logger Middleware

import { StateCreator, StoreMutatorIdentifier } from 'zustand'

type Logger = <T>(
  f: StateCreator<T, [], []>,
  name?: string,
) => StateCreator<T, [], []>

const logger: Logger = (f, name) => (set, get, store) => {
  const loggedSet: typeof set = (...a) => {
    const before = get()
    set(...(a as Parameters<typeof set>))
    const after = get()
    console.log(`[${name ?? 'store'}]`, { before, after })
  }
  return f(loggedSet, get, store)
}

// Use custom middleware
const useStore = create<MyStore>()(
  logger((set) => ({
    count: 0,
    increment: () => set((state) => ({ count: state.count + 1 })),
  }), 'CounterStore'),
)

Timestamp Middleware

type WithTimestamp<T> = T & { _lastUpdated: number }

const timestamp = <T>(f: StateCreator<T, [], []>): StateCreator<WithTimestamp<T>, [], []> =>
  (set, get, store) => ({
    ...f(
      (partial, replace) => {
        set(
          (state) => ({
            ...(typeof partial === 'function' ? partial(state as T) : partial),
            _lastUpdated: Date.now(),
          }) as WithTimestamp<T>,
          replace,
        )
      },
      get as () => T,
      store,
    ),
    _lastUpdated: Date.now(),
  })

---

Immer Middleware (Mutable Updates)

Write mutable update syntax that becomes immutable under the hood.

import { create } from 'zustand'
import { immer } from 'zustand/middleware/immer'

interface TodoStore {
  todos: Array<{ id: string; text: string; done: boolean }>
  addTodo: (text: string) => void
  toggleTodo: (id: string) => void
  removeTodo: (id: string) => void
}

const useStore = create<TodoStore>()(
  immer((set) => ({
    todos: [],
    addTodo: (text) =>
      set((state) => {
        // Mutate directly with Immer
        state.todos.push({ id: Date.now().toString(), text, done: false })
      }),
    toggleTodo: (id) =>
      set((state) => {
        const todo = state.todos.find((t) => t.id === id)
        if (todo) todo.done = !todo.done
      }),
    removeTodo: (id) =>
      set((state) => {
        const index = state.todos.findIndex((t) => t.id === id)
        if (index !== -1) state.todos.splice(index, 1)
      }),
  })),
)

When to use Immer:

• Deeply nested state updates
• Complex array manipulations
• Team familiarity with mutable patterns

When NOT to use Immer:

• Simple state
• Performance-critical apps (Immer adds overhead)
• Small bundle size requirements

---

Subscriptions and Side Effects

React to state changes outside components.

// Subscribe to specific state changes
const unsubscribe = useStore.subscribe(
  (state) => state.count,
  (count, prevCount) => {
    console.log('Count changed from', prevCount, 'to', count)

    // Trigger side effect
    if (count > 10) {
      analytics.track('count_exceeded_10')
    }
  },
)

// Subscribe with selector and equality function
import { shallow } from 'zustand/shallow'

useStore.subscribe(
  (state) => ({ count: state.count, name: state.name }),
  (selection, prevSelection) => {
    console.log('Selection changed:', selection)
  },
  { equalityFn: shallow },
)

Transient Updates (No Re-render)

Update state without triggering re-renders.

const useStore = create<{
  x: number
  y: number
  setPosition: (x: number, y: number) => void
}>()((set) => ({
  x: 0,
  y: 0,
  setPosition: (x, y) => set({ x, y }, true), // Replace, don't merge
}))

// Subscribe to track position without React re-renders
const unsubscribe = useStore.subscribe(console.log)

---

Testing Zustand Stores

Unit Testing Stores

import { act, renderHook } from '@testing-library/react'
import { useCounterStore } from './counterStore'

describe('counterStore', () => {
  beforeEach(() => {
    // Reset store between tests
    useCounterStore.setState({ count: 0 })
  })

  it('should increment count', () => {
    const { result } = renderHook(() => useCounterStore())

    act(() => {
      result.current.increment()
    })

    expect(result.current.count).toBe(1)
  })

  it('should decrement count', () => {
    useCounterStore.setState({ count: 5 })
    const { result } = renderHook(() => useCounterStore())

    act(() => {
      result.current.decrement()
    })

    expect(result.current.count).toBe(4)
  })
})

Testing with Persist Middleware

import { usePersistedStore } from './persistedStore'

describe('persistedStore', () => {
  beforeEach(() => {
    // Clear localStorage
    localStorage.clear()
    // Reset store
    usePersistedStore.setState({ value: '' })
  })

  it('should persist to localStorage', async () => {
    const { result } = renderHook(() => usePersistedStore())

    act(() => {
      result.current.setValue('test')
    })

    // Wait for persist
    await new Promise((r) => setTimeout(r, 0))

    expect(localStorage.getItem('persisted-store')).toContain('test')
  })
})

---

Performance Optimization

Fine-Grained Selectors

// ❌ Subscribes to entire store
const { count, name, items } = useStore()

// ✅ Subscribes only to what's needed
const count = useStore((state) => state.count)
const name = useStore((state) => state.name)

Memoized Selectors

import { useMemo } from 'react'

function ExpensiveList() {
  const items = useStore((state) => state.items)

  // Memoize expensive computation
  const sortedItems = useMemo(
    () => [...items].sort((a, b) => a.name.localeCompare(b.name)),
    [items],
  )

  return <ul>{sortedItems.map((item) => <li key={item.id}>{item.name}</li>)}</ul>
}

Batched Updates

const useStore = create<MyStore>()((set) => ({
  count: 0,
  name: '',
  // Batch multiple updates
  updateBoth: (count: number, name: string) =>
    set({ count, name }), // Single update, single re-render
}))

---

Summary

---

See Also

• middleware-guide.md - Built-in middleware details
• typescript-patterns.md - TypeScript-specific patterns
• Official docs: https://zustand.docs.pmnd.rs/

Common Zustand Patterns - Detailed Examples

This reference provides complete implementations for common Zustand patterns.

---

Pattern: Computed/Derived Values

Compute values in selectors, not in the store itself.

interface StoreWithComputed {
  items: string[]
  addItem: (item: string) => void
  // Computed in selector, not stored
}

const useStore = create<StoreWithComputed>()((set) => ({
  items: [],
  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
}))

// Use in component
function ItemCount() {
  const count = useStore((state) => state.items.length)
  return <div>{count} items</div>
}

// More complex computed values
function ExpensiveItems() {
  const expensive = useStore((state) =>
    state.items.filter((item) => item.startsWith('expensive'))
  )
  return <div>{expensive.length} expensive items</div>
}

Key Points:

• Compute in selector, not store
• Memoize expensive computations with useMemo if needed
• Selectors run on every render - keep them fast

---

Pattern: Async Actions

Handle asynchronous operations with loading and error states.

interface AsyncStore {
  data: string | null
  isLoading: boolean
  error: string | null
  fetchData: () => Promise<void>
}

const useAsyncStore = create<AsyncStore>()((set) => ({
  data: null,
  isLoading: false,
  error: null,
  fetchData: async () => {
    set({ isLoading: true, error: null })
    try {
      const response = await fetch('/api/data')
      if (!response.ok) throw new Error('Failed to fetch')
      const data = await response.text()
      set({ data, isLoading: false })
    } catch (error) {
      set({ error: (error as Error).message, isLoading: false })
    }
  },
}))

// Use in component
function DataDisplay() {
  const { data, isLoading, error, fetchData } = useAsyncStore()

  useEffect(() => {
    fetchData()
  }, [fetchData])

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error}</div>
  return <div>{data}</div>
}

Best Practice: For complex server state, consider TanStack Query instead.

---

Pattern: Resetting Store

Reset store to initial values (useful for logout, form reset, etc.).

interface ResettableStore {
  count: number
  name: string
  increment: () => void
  setName: (name: string) => void
  reset: () => void
}

const initialState = {
  count: 0,
  name: '',
}

const useStore = create<ResettableStore>()((set) => ({
  ...initialState,
  increment: () => set((state) => ({ count: state.count + 1 })),
  setName: (name) => set({ name }),
  reset: () => set(initialState),
}))

// Use in component
function LogoutButton() {
  const reset = useStore((state) => state.reset)

  const handleLogout = () => {
    // Clear user session
    reset() // Reset store to initial state
  }

  return <button onClick={handleLogout}>Logout</button>
}

---

Pattern: Selector with Params

Create parameterized selectors for dynamic data access.

interface TodoStore {
  todos: Array<{ id: string; text: string; done: boolean }>
  addTodo: (text: string) => void
  toggleTodo: (id: string) => void
}

const useStore = create<TodoStore>()((set) => ({
  todos: [],
  addTodo: (text) =>
    set((state) => ({
      todos: [...state.todos, { id: Date.now().toString(), text, done: false }],
    })),
  toggleTodo: (id) =>
    set((state) => ({
      todos: state.todos.map((todo) =>
        todo.id === id ? { ...todo, done: !todo.done } : todo
      ),
    })),
}))

// Use with parameter
function Todo({ id }: { id: string }) {
  const todo = useStore((state) => state.todos.find((t) => t.id === id))
  const toggleTodo = useStore((state) => state.toggleTodo)

  if (!todo) return null

  return (
    <div>
      <input
        type="checkbox"
        checked={todo.done}
        onChange={() => toggleTodo(id)}
      />
      {todo.text}
    </div>
  )
}

// Filtered todos
function CompletedTodos() {
  const completedTodos = useStore((state) =>
    state.todos.filter((t) => t.done)
  )
  return <div>{completedTodos.length} completed</div>
}

---

Pattern: Multiple Stores

Separate concerns with multiple independent stores.

// userStore.ts
interface UserStore {
  user: { id: string; name: string } | null
  setUser: (user: UserStore['user']) => void
  logout: () => void
}

export const useUserStore = create<UserStore>()((set) => ({
  user: null,
  setUser: (user) => set({ user }),
  logout: () => set({ user: null }),
}))

// cartStore.ts
interface CartStore {
  items: Array<{ id: string; quantity: number }>
  addItem: (id: string) => void
  removeItem: (id: string) => void
  clearCart: () => void
}

export const useCartStore = create<CartStore>()((set) => ({
  items: [],
  addItem: (id) =>
    set((state) => {
      const existing = state.items.find((i) => i.id === id)
      if (existing) {
        return {
          items: state.items.map((i) =>
            i.id === id ? { ...i, quantity: i.quantity + 1 } : i
          ),
        }
      }
      return { items: [...state.items, { id, quantity: 1 }] }
    }),
  removeItem: (id) =>
    set((state) => ({
      items: state.items.filter((i) => i.id !== id),
    })),
  clearCart: () => set({ items: [] }),
}))

// Use in components
function Header() {
  const user = useUserStore((state) => state.user)
  const itemCount = useCartStore((state) => state.items.length)

  return (
    <header>
      <span>{user?.name ?? 'Guest'}</span>
      <span>Cart: {itemCount}</span>
    </header>
  )
}

---

Pattern: Cross-Store Actions

Access one store from another for complex workflows.

// Use getState() to access store outside React
const useAuthStore = create<AuthStore>()((set) => ({
  isAuthenticated: false,
  login: () => set({ isAuthenticated: true }),
  logout: () => {
    set({ isAuthenticated: false })
    // Clear cart when logging out
    useCartStore.getState().clearCart()
  },
}))

---

Summary Table

---

See Also

• Main SKILL.md for basic patterns
• templates/ for copy-paste implementations
• typescript-patterns.md for advanced typing

[TODO: Reference Document Name]

[TODO: This file contains reference documentation that Claude can load when needed.]

[TODO: Delete this file if you don't have reference documentation to provide.]

Purpose

[TODO: Explain what information this document contains]

When Claude Should Use This

[TODO: Describe specific scenarios where Claude should load this reference]

Content

[TODO: Add your reference content here - schemas, guides, specifications, etc.]

---

Note: This file is NOT loaded into context by default. Claude will only load it when:

• It determines the information is needed
• You explicitly ask Claude to reference it
• The SKILL.md instructions direct Claude to read it

Keep this file under 10k words for best performance.

Known Issues Prevention - Detailed Solutions

This reference covers the 5 most common Zustand issues with complete solutions.

---

Issue #1: Next.js Hydration Mismatch

Error: "Text content does not match server-rendered HTML" or "Hydration failed"

Source:

• DEV Community: Persist middleware in Next.js
• GitHub Discussions #2839

Why It Happens: Persist middleware reads from localStorage on client but not on server, causing state mismatch.

Prevention:

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

interface StoreWithHydration {
  count: number
  _hasHydrated: boolean
  setHasHydrated: (hydrated: boolean) => void
  increase: () => void
}

const useStore = create<StoreWithHydration>()(
  persist(
    (set) => ({
      count: 0,
      _hasHydrated: false,
      setHasHydrated: (hydrated) => set({ _hasHydrated: hydrated }),
      increase: () => set((state) => ({ count: state.count + 1 })),
    }),
    {
      name: 'my-store',
      onRehydrateStorage: () => (state) => {
        state?.setHasHydrated(true)
      },
    },
  ),
)

// In component
function MyComponent() {
  const hasHydrated = useStore((state) => state._hasHydrated)

  if (!hasHydrated) {
    return <div>Loading...</div>
  }

  // Now safe to render with persisted state
  return <ActualContent />
}

---

Issue #2: TypeScript Double Parentheses Missing

Error: Type inference fails, StateCreator types break with middleware

Source: Official Zustand TypeScript Guide

Why It Happens: The currying syntax create<T>()() is required for middleware to work with TypeScript inference.

Prevention:

// ❌ WRONG - Single parentheses
const useStore = create<MyStore>((set) => ({
  // ...
}))

// ✅ CORRECT - Double parentheses
const useStore = create<MyStore>()((set) => ({
  // ...
}))

Rule: Always use create<T>()() in TypeScript, even without middleware (future-proof).

---

Issue #3: Persist Middleware Import Error

Error: "Attempted import error: 'createJSONStorage' is not exported from 'zustand/middleware'"

Source: GitHub Discussion #2839

Why It Happens: Wrong import path or version mismatch between zustand and build tools.

Prevention:

// ✅ CORRECT imports for v5
import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'

// Verify versions
// zustand@5.0.8 includes createJSONStorage
// zustand@4.x uses different API

// Check your package.json
// "zustand": "^5.0.8"

---

Issue #4: Infinite Render Loop

Error: Component re-renders infinitely, browser freezes

Source: GitHub Discussions #2642

Why It Happens: Creating new object references in selectors causes Zustand to think state changed.

Prevention:

import { shallow } from 'zustand/shallow'

// ❌ WRONG - Creates new object every time
const { bears, fishes } = useStore((state) => ({
  bears: state.bears,
  fishes: state.fishes,
}))

// ✅ CORRECT Option 1 - Select primitives separately
const bears = useStore((state) => state.bears)
const fishes = useStore((state) => state.fishes)

// ✅ CORRECT Option 2 - Use shallow for multiple values
const { bears, fishes } = useStore(
  (state) => ({ bears: state.bears, fishes: state.fishes }),
  shallow,
)

---

Issue #5: Slices Pattern TypeScript Complexity

Error: StateCreator types fail to infer, complex middleware types break

Source: Official Slices Pattern Guide

Why It Happens: Combining multiple slices requires explicit type annotations for middleware compatibility.

Prevention:

import { create, StateCreator } from 'zustand'

// Define slice types
interface BearSlice {
  bears: number
  addBear: () => void
}

interface FishSlice {
  fishes: number
  addFish: () => void
}

// Create slices with proper types
const createBearSlice: StateCreator<
  BearSlice & FishSlice,  // Combined store type
  [],                      // Middleware mutators (empty if none)
  [],                      // Chained middleware (empty if none)
  BearSlice               // This slice's type
> = (set) => ({
  bears: 0,
  addBear: () => set((state) => ({ bears: state.bears + 1 })),
})

const createFishSlice: StateCreator<
  BearSlice & FishSlice,
  [],
  [],
  FishSlice
> = (set) => ({
  fishes: 0,
  addFish: () => set((state) => ({ fishes: state.fishes + 1 })),
})

// Combine slices
const useStore = create<BearSlice & FishSlice>()((...a) => ({
  ...createBearSlice(...a),
  ...createFishSlice(...a),
}))

---

Quick Reference Table

---

See Also

• nextjs-hydration.md - More Next.js SSR patterns
• typescript-patterns.md - Advanced TypeScript solutions
• middleware-guide.md - Middleware configuration details

Zustand Middleware Complete Guide

Complete reference for all Zustand middleware. Load when user asks about persistence, devtools, immer, or custom middleware.

---

Persist Middleware

Basic Usage

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

const useStore = create<Store>()(
  persist(
    (set) => ({ /* store */ }),
    { name: 'storage-name' }
  )
)

Storage Options

// localStorage (default)
storage: createJSONStorage(() => localStorage)

// sessionStorage
storage: createJSONStorage(() => sessionStorage)

// Custom storage
storage: createJSONStorage(() => customStorage)

Partial Persistence

persist(
  (set) => ({ /* store */ }),
  {
    name: 'storage',
    partialize: (state) => ({
      theme: state.theme,
      // Don't persist sensitive data
    }),
  }
)

Schema Migration

persist(
  (set) => ({ /* store */ }),
  {
    name: 'storage',
    version: 2,
    migrate: (persistedState: any, version) => {
      if (version === 0) {
        // v0 → v1
        persistedState.newField = 'default'
      }
      if (version === 1) {
        // v1 → v2
        delete persistedState.oldField
      }
      return persistedState
    },
  }
)

---

Devtools Middleware

Basic Usage

import { devtools } from 'zustand/middleware'

const useStore = create<Store>()(
  devtools(
    (set) => ({ /* store */ }),
    { name: 'StoreName' }
  )
)

Named Actions

increment: () => set(
  (state) => ({ count: state.count + 1 }),
  undefined,
  'counter/increment' // Shows in DevTools
)

Production Toggle

devtools(
  (set) => ({ /* store */ }),
  {
    name: 'Store',
    enabled: process.env.NODE_ENV === 'development'
  }
)

---

Immer Middleware

Allows mutable state updates (Immer handles immutability):

import { immer } from 'zustand/middleware/immer'

const useStore = create<Store>()(
  immer((set) => ({
    todos: [],
    addTodo: (text) => set((state) => {
      // Mutate directly!
      state.todos.push({ id: Date.now(), text })
    }),
  }))
)

When to use: Complex nested state updates

---

Combining Middlewares

Order Matters

// ✅ CORRECT: devtools wraps persist
const useStore = create<Store>()(
  devtools(
    persist(
      (set) => ({ /* store */ }),
      { name: 'storage' }
    ),
    { name: 'Store' }
  )
)

// Shows persist actions in DevTools

Common Combinations

// Persist + Devtools
devtools(persist(...), { name: 'Store' })

// Persist + Immer
persist(immer(...), { name: 'storage' })

// All three
devtools(
  persist(
    immer(...),
    { name: 'storage' }
  ),
  { name: 'Store' }
)

---

Custom Middleware

Logger Example

const logger = (config) => (set, get, api) => {
  return config(
    (...args) => {
      console.log('Before:', get())
      set(...args)
      console.log('After:', get())
    },
    get,
    api
  )
}

const useStore = create(logger((set) => ({ /* store */ })))

TypeScript Logger

import { StateCreator } from 'zustand'

type Logger = <T>(
  f: StateCreator<T, [], []>,
  name?: string
) => StateCreator<T, [], []>

const logger: Logger = (f, name) => (set, get, store) => {
  const loggedSet: typeof set = (...a) => {
    set(...(a as Parameters<typeof set>))
    console.log(`[${name}]:`, get())
  }
  return f(loggedSet, get, store)
}

---

Middleware API Reference

persist()

persist<T>(
  stateCreator: StateCreator<T>,
  options: {
    name: string                    // Storage key (required)
    storage?: PersistStorage<T>     // Storage engine
    partialize?: (state: T) => Partial<T>  // Select what to persist
    version?: number                // Schema version
    migrate?: (state: any, version: number) => T  // Migration function
    merge?: (persisted: any, current: T) => T     // Custom merge
    onRehydrateStorage?: (state: T) => void       // Hydration callback
  }
)

devtools()

devtools<T>(
  stateCreator: StateCreator<T>,
  options?: {
    name?: string      // Store name in DevTools
    enabled?: boolean  // Enable/disable
  }
)

immer()

immer<T>(
  stateCreator: StateCreator<T>
)

---

Common Patterns

Reset Store

const initialState = { count: 0 }

const useStore = create<Store>()(
  persist(
    (set) => ({
      ...initialState,
      reset: () => set(initialState),
    }),
    { name: 'storage' }
  )
)

Clear Persisted Data

// Clear localStorage
localStorage.removeItem('storage-name')

// Or programmatically
const useStore = create<Store>()(
  persist(
    (set) => ({
      clearStorage: () => {
        localStorage.removeItem('storage-name')
        set(initialState)
      },
    }),
    { name: 'storage-name' }
  )
)

---

Official Documentation

• Persist: https://github.com/pmndrs/zustand/blob/main/docs/integrations/persisting-store-data.md
• Devtools: https://github.com/pmndrs/zustand/blob/main/docs/middlewares/devtools.md
• Immer: https://github.com/pmndrs/zustand/blob/main/docs/middlewares/immer.md

Migrating to Zustand

Guide for migrating from Redux, Context API, or Zustand v4. Load when user is migrating state management.

---

From Redux to Zustand

Before (Redux)

// Action types
const INCREMENT = 'INCREMENT'
const DECREMENT = 'DECREMENT'

// Actions
const increment = () => ({ type: INCREMENT })
const decrement = () => ({ type: DECREMENT })

// Reducer
const reducer = (state = { count: 0 }, action) => {
  switch (action.type) {
    case INCREMENT:
      return { count: state.count + 1 }
    case DECREMENT:
      return { count: state.count - 1 }
    default:
      return state
  }
}

// Store
const store = createStore(reducer)

// Provider
<Provider store={store}>
  <App />
</Provider>

// Component
const count = useSelector((state) => state.count)
const dispatch = useDispatch()
<button onClick={() => dispatch(increment())}>Increment</button>

After (Zustand)

// Store (all in one!)
import { create } from 'zustand'

interface Store {
  count: number
  increment: () => void
  decrement: () => void
}

const useStore = create<Store>()((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
}))

// No provider needed!

// Component
const count = useStore((state) => state.count)
const increment = useStore((state) => state.increment)
<button onClick={increment}>Increment</button>

Benefits:

• ~90% less boilerplate
• No provider wrapper
• No action types/creators
• No reducer switch
• Built-in TypeScript support

---

From Context API to Zustand

Before (Context)

// Context
const CountContext = createContext(null)

// Provider
function CountProvider({ children }) {
  const [count, setCount] = useState(0)

  const increment = () => setCount((c) => c + 1)
  const decrement = () => setCount((c) => c - 1)

  return (
    <CountContext.Provider value={{ count, increment, decrement }}>
      {children}
    </CountContext.Provider>
  )
}

// Hook
function useCount() {
  const context = useContext(CountContext)
  if (!context) throw new Error('useCount must be within CountProvider')
  return context
}

// App
<CountProvider>
  <App />
</CountProvider>

// Component
const { count, increment } = useCount()

After (Zustand)

// Store
const useStore = create<Store>()((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
}))

// Component (no provider needed!)
const count = useStore((state) => state.count)
const increment = useStore((state) => state.increment)

Benefits:

• No provider needed
• No context null checks
• No wrapper components
• Better performance (no context re-renders)
• Persistent by default (with middleware)

---

From Zustand v4 to v5

Breaking Changes

1. TypeScript Syntax

// ❌ v4
const useStore = create<Store>((set) => ({ /* ... */ }))

// ✅ v5
const useStore = create<Store>()((set) => ({ /* ... */ }))
//                            ^^ Double parentheses required

2. Persist Middleware Imports

// ❌ v4
import { persist } from 'zustand/middleware'

const useStore = create(
  persist((set) => ({ /* ... */ }), { name: 'storage' })
)

// ✅ v5
import { persist, createJSONStorage } from 'zustand/middleware'

const useStore = create<Store>()(
  persist(
    (set) => ({ /* ... */ }),
    {
      name: 'storage',
      storage: createJSONStorage(() => localStorage),
    }
  )
)

3. Shallow Import

// ❌ v4
import shallow from 'zustand/shallow'

// ✅ v5
import { shallow } from 'zustand/shallow'

---

Migration Strategies

Gradual Migration

1. Install Zustand alongside existing solution 2. Migrate one feature at a time 3. Test thoroughly before moving to next 4. Remove old code once stable

Big Bang Migration

1. Create Zustand stores for all state 2. Update all components at once 3. Remove old state management entirely 4. Test everything

Recommendation: Gradual migration for large apps.

---

Code Mapping

Redux → Zustand

Context → Zustand

---

Common Pitfalls

1. Forgetting Double Parentheses (v5)

// ❌ WRONG
create<Store>((set) => ({ /* ... */ }))

// ✅ CORRECT
create<Store>()((set) => ({ /* ... */ }))

2. Creating Objects in Selectors

// ❌ WRONG - Causes infinite renders
const { a, b } = useStore((state) => ({ a: state.a, b: state.b }))

// ✅ CORRECT
const a = useStore((state) => state.a)
const b = useStore((state) => state.b)

3. Not Using Persist Correctly

// ❌ WRONG - Missing createJSONStorage
persist((set) => ({ /* ... */ }), { name: 'storage' })

// ✅ CORRECT
persist(
  (set) => ({ /* ... */ }),
  {
    name: 'storage',
    storage: createJSONStorage(() => localStorage),
  }
)

---

Checklist

• [ ] Installed Zustand v5+
• [ ] Created store with create<T>()()
• [ ] Removed Context providers (if migrating from Context)
• [ ] Removed Redux boilerplate (if migrating from Redux)
• [ ] Updated all useSelector to Zustand selectors
• [ ] Updated all useDispatch to direct function calls
• [ ] Added persist if state needs persistence
• [ ] Added devtools if using Redux DevTools
• [ ] Tested all components
• [ ] Verified no hydration errors (Next.js)
• [ ] Removed old state management code

---

Official Resources

• Zustand Docs: https://zustand.docs.pmnd.rs/
• Migration Guide: https://github.com/pmndrs/zustand/wiki/Migrating-to-v4
• TypeScript Guide: https://zustand.docs.pmnd.rs/guides/typescript

Zustand + Next.js Hydration Guide

Complete guide for using Zustand with Next.js SSR. Load for Next.js-specific problems.

---

The Hydration Problem

Error: "Text content does not match server-rendered HTML"

Why it happens:

• Server renders with default state
• Client loads persisted state from localStorage
• Content doesn't match → hydration error

---

Solution: Hydration Flag Pattern

Store Setup

'use client'

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

interface Store {
  _hasHydrated: boolean  // Track hydration
  count: number
  setHasHydrated: (hydrated: boolean) => void
  increment: () => void
}

export const useStore = create<Store>()(
  persist(
    (set) => ({
      _hasHydrated: false,
      count: 0,
      setHasHydrated: (hydrated) => set({ _hasHydrated: hydrated }),
      increment: () => set((state) => ({ count: state.count + 1 })),
    }),
    {
      name: 'storage',
      onRehydrateStorage: () => (state) => {
        state?.setHasHydrated(true)  // Set true when done
      },
    },
  ),
)

Component Usage

'use client'

function Component() {
  const hasHydrated = useStore((state) => state._hasHydrated)
  const count = useStore((state) => state.count)

  if (!hasHydrated) {
    return <div>Loading...</div>
  }

  return <div>Count: {count}</div>
}

---

Alternative: Accept Flash

If loading state is unacceptable, accept brief flash:

'use client'

function Component() {
  const count = useStore((state) => state.count)

  // Will show default (0) briefly, then correct value
  return <div>Count: {count}</div>
}

Trade-off: Simpler code, but user sees flash.

---

App Router vs Pages Router

App Router (Recommended)

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html>
      <body>{children}</body>
    </html>
  )
}

// app/page.tsx
'use client'

import { useStore } from './store'

export default function Page() {
  return <Component />
}

Note: Add 'use client' to components using Zustand.

Pages Router

// pages/_app.tsx
export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />
}

// pages/index.tsx
import { useStore } from '../store'

export default function Page() {
  return <Component />
}

Note: No 'use client' needed in Pages Router.

---

Server Components

NEVER use Zustand in Server Components:

// ❌ WRONG - Server Component
export default async function ServerComponent() {
  const count = useStore((state) => state.count)  // Error!
  return <div>{count}</div>
}

// ✅ CORRECT - Client Component
'use client'

export default function ClientComponent() {
  const count = useStore((state) => state.count)
  return <div>{count}</div>
}

---

SSR with getServerSideProps

// pages/index.tsx
import { GetServerSideProps } from 'next'

export const getServerSideProps: GetServerSideProps = async () => {
  // Fetch data on server
  const data = await fetchData()

  return {
    props: { data },
  }
}

export default function Page({ data }) {
  const setData = useStore((state) => state.setData)

  // Sync server data to store
  useEffect(() => {
    setData(data)
  }, [data, setData])

  return <Component />
}

---

Common Patterns

Initialize Store from Props

'use client'

function Page({ serverData }) {
  const setData = useStore((state) => state.setData)

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

  return <Component />
}

Conditional Rendering

'use client'

function Component() {
  const hasHydrated = useStore((state) => state._hasHydrated)
  const theme = useStore((state) => state.theme)

  return (
    <div className={hasHydrated ? theme : 'default'}>
      {hasHydrated ? <Content /> : <Skeleton />}
    </div>
  )
}

Progressive Enhancement

'use client'

function Component() {
  const hasHydrated = useStore((state) => state._hasHydrated)
  const preferences = useStore((state) => state.preferences)

  // Always render, but enhance after hydration
  return (
    <div>
      <DefaultUI />
      {hasHydrated && <EnhancedUI preferences={preferences} />}
    </div>
  )
}

---

Debugging Hydration Errors

Enable Strict Mode

// next.config.js
module.exports = {
  reactStrictMode: true,
}

Check for Differences

useEffect(() => {
  console.log('Server state:', defaultState)
  console.log('Client state:', persistedState)
}, [])

Use React DevTools

Look for red warnings about hydration mismatches.

---

Official Resources

• Next.js Hydration: https://nextjs.org/docs/messages/react-hydration-error
• Zustand Persist: https://github.com/pmndrs/zustand/blob/main/docs/integrations/persisting-store-data.md
• DEV.to Guide: https://dev.to/abdulsamad/how-to-use-zustands-persist-middleware-in-nextjs-4lb5

Zustand TypeScript Advanced Patterns

Advanced TypeScript patterns and troubleshooting. Load when encountering complex type inference issues.

---

Basic TypeScript Setup

The Golden Rule: Double Parentheses

// ✅ CORRECT
const useStore = create<Store>()((set) => ({ /* ... */ }))

// ❌ WRONG
const useStore = create<Store>((set) => ({ /* ... */ }))

Why: Currying syntax enables middleware type inference.

---

Store Interface Pattern

// Define types
interface BearState {
  bears: number
}

interface BearActions {
  increase: (by: number) => void
  decrease: (by: number) => void
}

// Combine
type BearStore = BearState & BearActions

// Use
const useBearStore = create<BearStore>()((set) => ({
  bears: 0,
  increase: (by) => set((state) => ({ bears: state.bears + by })),
  decrease: (by) => set((state) => ({ bears: state.bears - by })),
}))

---

Slices Pattern Types

import { StateCreator } from 'zustand'

// Define slice type
interface BearSlice {
  bears: number
  addBear: () => void
}

// Create slice with proper types
const createBearSlice: StateCreator<
  BearSlice & FishSlice,  // Combined store type
  [],                      // Middleware mutators
  [],                      // Chained middleware
  BearSlice               // This slice
> = (set) => ({
  bears: 0,
  addBear: () => set((state) => ({ bears: state.bears + 1 })),
})

---

Middleware Types

With Devtools

import { StateCreator } from 'zustand'
import { devtools } from 'zustand/middleware'

interface Store {
  count: number
  increment: () => void
}

const useStore = create<Store>()(
  devtools(
    (set) => ({
      count: 0,
      increment: () =>
        set(
          (state) => ({ count: state.count + 1 }),
          undefined,
          'increment'
        ),
    }),
    { name: 'Store' }
  )
)

With Persist

import { persist } from 'zustand/middleware'

const useStore = create<Store>()(
  persist(
    (set) => ({ /* ... */ }),
    { name: 'storage' }
  )
)

With Multiple Middlewares

const useStore = create<Store>()(
  devtools(
    persist(
      (set) => ({ /* ... */ }),
      { name: 'storage' }
    ),
    { name: 'Store' }
  )
)

---

Slices with Middleware

import { StateCreator } from 'zustand'
import { devtools } from 'zustand/middleware'

const createBearSlice: StateCreator<
  BearSlice & FishSlice,
  [['zustand/devtools', never]],  // Add devtools mutator
  [],
  BearSlice
> = (set) => ({
  bears: 0,
  addBear: () =>
    set(
      (state) => ({ bears: state.bears + 1 }),
      undefined,
      'bear/add'
    ),
})

---

Selector Types

Basic Selector

const bears = useStore((state) => state.bears)
// Type: number

Computed Selector

const selectTotal = (state: Store) => state.items.reduce((sum, item) => sum + item.price, 0)

const total = useStore(selectTotal)
// Type: number

Parameterized Selector

const selectById = (id: string) => (state: Store) =>
  state.items.find((item) => item.id === id)

const item = useStore(selectById('123'))
// Type: Item | undefined

---

Vanilla Store Types

import { createStore } from 'zustand/vanilla'

const store = createStore<Store>()((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}))

// Get state
const state = store.getState()
// Type: Store

// Subscribe
const unsubscribe = store.subscribe((state) => {
  // state is typed as Store
})

---

Custom Hook with Types

import { useStore } from 'zustand'

const bearStore = createStore<BearStore>()((set) => ({
  bears: 0,
  increase: () => set((state) => ({ bears: state.bears + 1 })),
}))

// Create custom hook
function useBearStore<T>(selector: (state: BearStore) => T): T {
  return useStore(bearStore, selector)
}

---

Common Type Errors

Error: Type inference breaks

Problem: Using single parentheses

// ❌ WRONG
const useStore = create<Store>((set) => ({ /* ... */ }))

Solution: Use double parentheses

// ✅ CORRECT
const useStore = create<Store>()((set) => ({ /* ... */ }))

Error: StateCreator types fail

Problem: Missing middleware mutators

// ❌ WRONG
const createSlice: StateCreator<CombinedStore, [], [], MySlice>

Solution: Add middleware mutators

// ✅ CORRECT
const createSlice: StateCreator<
  CombinedStore,
  [['zustand/devtools', never]],  // Add this
  [],
  MySlice
>

Error: Circular reference

Problem: Slices referencing each other

Solution: Define combined type first, then reference in slices

type AllSlices = BearSlice & FishSlice & SharedSlice

const createBearSlice: StateCreator<AllSlices, [], [], BearSlice> = ...

---

Official TypeScript Guide

https://zustand.docs.pmnd.rs/guides/typescript