zustand-state-management

Imported from mindrally/skills (zustand-state-management/SKILL.md) via skills.sh. Install upstream with npx skills add mindrally/skills --skill zustand-state-management. Copyright stays with the author.

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.

Non-React Subscriptions

• Use subscribeWithSelector for non-React subscriptions that need fine-grained updates outside of component rendering.

Async Actions & Error Handling

• Async store actions should coordinate client-only workflows, optimistic drafts, or local device APIs — keep HTTP fetching in the project's server-state layer unless the state is explicitly client-owned.
• Represent async client workflows with explicit statuses such as idle, pending, success, and error rather than ad hoc booleans.
• Handle errors at function start using early returns and guard clauses; use try-catch in async actions and provide meaningful error messages.
• Reset error state deliberately when retrying or closing a workflow.

SSR and React Server Components

• Do not read or mutate browser-only stores from React Server Components.
• In SSR frameworks (Next.js App Router, etc.), create per-request vanilla stores when state must be initialized on the server, rather than a shared module-level store.
• Guard persisted stores against hydration mismatches before rendering storage-backed values.
• Keep store modules free of direct window, document, and storage access outside middleware configuration.

Testing

• Test stores independently of components — test store actions directly without rendering React when possible.
• Reset stores between tests with their initial state.
• Assert selectors and actions separately from component behavior; mock Zustand stores in component tests when isolating UI logic.
• Mock server-state libraries instead of routing fetched data through Zustand for tests.
• Test middleware behavior (persistence, devtools) separately from core store logic.

Anti-Patterns

• Do not create one global store for the entire application.
• Do not put form input state in Zustand unless multiple distant components edit the same draft.
• Do not mutate nested objects directly without Immer middleware.
• Do not use Zustand as an event bus; prefer explicit callbacks, services, or a scoped store.
• Do not introduce Redux-style reducers, action constants, or dispatch wrappers unless the project already uses that pattern.