Zustand State Management

Zustand State Management

This skill covers designing and using Zustand stores in React and TypeScript applications, including state ownership decisions, store slicing, selector performance, middleware, SSR, and testing.

State Ownership

• Keep ephemeral UI state in the nearest component with useState or useReducer — don't reach for Zustand by default.
• Use URL state for shareable filters, pagination, tabs, and search params.
• Use Zustand only for client state that is genuinely shared across unrelated components (auth session view state, command palette, cart draft, editor state, etc.).
• Use TanStack Query, SWR, RTK Query, or the project's existing data layer for server state — don't duplicate fetched server data into a Zustand store unless there's a documented offline or draft-editing requirement.
• Implement functional, declarative patterns; avoid classes. Use descriptive variable names with auxiliary verbs like isLoading, hasError.

Store Design

• Model each store as state plus named actions; avoid exposing anonymous setters for component code to misuse.
• Keep stores small and domain-focused rather than one global store for the entire application.
• Split large stores into typed slices, then apply middleware only at the composed store boundary.
• Keep derived values as selectors or small pure helpers unless they must be cached in state.
• Store serializable data by default; keep DOM nodes, promises, sockets, and timers outside store state.

import { create } from 'zustand'

interface SidebarState {
  isOpen: boolean
  activePanelId: string | null
}

interface SidebarActions {
  openPanel: (panelId: string) => void
  close: () => void
  toggle: () => void
}

type SidebarStore = SidebarState & SidebarActions

export const useSidebarStore = create<SidebarStore>()((set) => ({
  isOpen: false,
  activePanelId: null,
  openPanel: (panelId) => set({ isOpen: true, activePanelId: panelId }),
  close: () => set({ isOpen: false, activePanelId: null }),
  toggle: () => set((state) => ({ isOpen: !state.isOpen })),
}))

Component Usage & Performance

• Subscribe to the smallest possible slice: useStore((state) => state.value). Avoid selecting the entire store.
• Do not call a store hook without a selector in components unless the component truly needs every field.
• Use useShallow (from zustand/react/shallow) when a selector returns an object or tuple of multiple values, to avoid re-renders from a new object reference each call.
• Keep selectors pure and cheap; move expensive derivations into memoized helpers.

import { useShallow } from 'zustand/react/shallow'
import { useSidebarStore } from '@/stores/sidebar-store'

export function SidebarToggle() {
  const { isOpen, toggle } = useSidebarStore(
    useShallow((state) => ({
      isOpen: state.isOpen,
      toggle: state.toggle,
    })),
  )

  return (
    <button type="button" aria-expanded={isOpen} onClick={toggle}>
      Toggle sidebar
    </button>
  )
}

TypeScript

• Define explicit state and action interfaces for shared stores; combine them (type Store = State & Actions) rather than one flat interface for non-trivial stores.
• Avoid any; use unknown plus narrowing for external data.
• Type action payloads and return values, including async actions.
• Prefer discriminated unions for complex local status instead of several loosely related booleans.
• Export store state types when tests, utilities, or vanilla store factories need them.

Middleware

Updates

• Use functional set((state) => nextState) when the next value depends on current state.
• Treat nested state immutably; install and use the immer middleware only when it materially simplifies nested updates — don't mutate nested objects directly without it.

Persistence

import { persist } from 'zustand/middleware'

const useStore = create(
  persist(
    (set) => ({
      // state and actions
    }),
    { name: 'store-key' }
  )
)

• Use persist only for state that must survive reloads.
• Use partialize, version, and migrate when persisting anything beyond trivial preferences.
• Never persist secrets, access tokens, refresh tokens, raw PII, or other long-lived authorization state to browser storage.

DevTools

import { devtools } from 'zustand/middleware'

const useStore = create(
  devtools((set) => ({
    // state and actions
  }))
)

• Use devtools in development for complex flows and give important actions clear names so they're identifiable in the trace.