zustand-state-management

secondsky 的头像作者 secondsky

用于React的TypeScript状态管理库Zustand。适用于全局状态管理、Redux/Context API迁移、localStorage持久化、slices模式、开发工具、Next.js SSR、处理 hydration 错误、TypeScript推断问题、持久化中间件问题或无限渲染循环。

📖 中文导读:用于React的TypeScript状态管理库Zustand。适用于全局状态管理、Redux/Context API迁移、localStorage持久化、slices模式、开发工具、Next.js SSR、处理 hydration 错误、TypeScript推断问题、持久化中间件问题或无限渲染循环。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: zustand-state-management description: Zustand state management for React with TypeScript. Use for global state, Redux/Context API migration, localStorage persistence, slices pattern, devtools, Next.js SSR, or encountering hydration errors, TypeScript inference issues, persist middleware problems, infinite render loops.

Keywords: zustand, state management, React state, TypeScript state, persist middleware, devtools, slices pattern, global state, React hooks, create store, useBoundStore, StateCreator, hydration error, text content mismatch, infinite render, localStorage, sessionStorage, immer middleware, shallow equality, selector pattern, zustand v5 license: MIT

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

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)

Issue Error Quick Fix
#1 Hydration mismatch "Text content does not match" Use _hasHydrated flag + onRehydrateStorage
#2 TypeScript inference Types break with middleware Use create<T>()() double parentheses
#3 Import error "createJSONStorage not exported" Upgrade to zustand@5.0.8+
#4 Infinite loop Browser freezes Use shallow or separate selectors
#5 Slices types StateCreator types fail Explicit StateCreator<Combined, [], [], Slice>

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' },
  ),
)
Middleware Purpose Import
persist localStorage/sessionStorage zustand/middleware
devtools Redux DevTools integration zustand/middleware
immer Mutable update syntax zustand/middleware/immer

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

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


Common Patterns

Pattern Use Case Key Technique
Computed values Derived data Compute in selector: state.items.length
Async actions API calls set({ isLoading: true }) + try/catch
Reset store Logout, form clear set(initialState)
Selector with params Dynamic access state.todos.find(t => t.id === id)
Multiple stores Separation of concerns Create separate create() calls

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


Advanced Topics

Topic Use Case Key API
Vanilla store Non-React, testing createStore() from zustand/vanilla
Custom middleware Logging, timestamps Wrap StateCreator
Immer Mutable update syntax immer() middleware
Subscriptions Side effects store.subscribe()

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


Bundled Resources

Type Files
Templates basic-store.ts, typescript-store.ts, persist-store.ts, slices-pattern.ts, devtools-store.ts, nextjs-store.ts, computed-store.ts, async-actions-store.ts
References middleware-guide.md, typescript-patterns.md, nextjs-hydration.md, migration-guide.md, known-issues.md, common-patterns.md, advanced-topics.md

When to Load References

Reference Load When...
known-issues.md Debugging hydration, TypeScript, infinite loop, or slices errors
common-patterns.md Implementing computed values, async actions, reset patterns
advanced-topics.md Vanilla stores, custom middleware, Immer, subscriptions
middleware-guide.md Configuring persist, devtools, or combining middlewares
typescript-patterns.md Complex type inference issues, StateCreator problems
nextjs-hydration.md Next.js SSR/hydration problems
migration-guide.md Migrating from Redux, Context API, or Zustand v4

Quick Troubleshooting

Problem Solution
Store updates don't trigger re-renders Use selector: useStore(state => state.value) not destructuring
TypeScript errors with middleware Use create<T>()() double parentheses
Hydration error with persist Implement _hasHydrated flag pattern
Actions not showing in DevTools Pass action name: set(newState, undefined, 'actionName')
Store resets unexpectedly HMR causes reset in development

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