Back to Details

zustand-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zustand State Management Patterns

Zustand 状态管理模式

Basic Store

基础 Store

Simple Store

简单 Store

tsx
// stores/counter.ts
import { create } from 'zustand';

interface CounterState {
  count: number;
  increment: () => void;
  decrement: () => void;
  reset: () => void;
}

export const useCounterStore = create<CounterState>((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
  reset: () => set({ count: 0 }),
}));
tsx
// stores/counter.ts
import { create } from 'zustand';

interface CounterState {
  count: number;
  increment: () => void;
  decrement: () => void;
  reset: () => void;
}

export const useCounterStore = create<CounterState>((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
  reset: () => set({ count: 0 }),
}));

Usage

使用方式

tsx
'use client';

import { useCounterStore } from '@/stores/counter';

export function Counter() {
  const count = useCounterStore((state) => state.count);
  const increment = useCounterStore((state) => state.increment);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
}
tsx
'use client';

import { useCounterStore } from '@/stores/counter';

export function Counter() {
  const count = useCounterStore((state) => state.count);
  const increment = useCounterStore((state) => state.increment);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
}

Store Patterns

Store 模式

Slice Pattern

切片模式

Split large stores into focused slices:
tsx
// stores/app-store.ts
import { create } from 'zustand';

// Auth slice
interface AuthSlice {
  user: User | null;
  isAuthenticated: boolean;
  login: (user: User) => void;
  logout: () => void;
}

const createAuthSlice = (set): AuthSlice => ({
  user: null,
  isAuthenticated: false,
  login: (user) => set({ user, isAuthenticated: true }),
  logout: () => set({ user: null, isAuthenticated: false }),
});

// UI slice
interface UISlice {
  sidebarOpen: boolean;
  toggleSidebar: () => void;
}

const createUISlice = (set): UISlice => ({
  sidebarOpen: true,
  toggleSidebar: () =>
    set((state) => ({ sidebarOpen: !state.sidebarOpen })),
});

// Combined store
type AppState = AuthSlice & UISlice;

export const useAppStore = create<AppState>()((...a) => ({
  ...createAuthSlice(...a),
  ...createUISlice(...a),
}));
将大型 Store 拆分为聚焦的切片：
tsx
// stores/app-store.ts
import { create } from 'zustand';

// Auth 切片
interface AuthSlice {
  user: User | null;
  isAuthenticated: boolean;
  login: (user: User) => void;
  logout: () => void;
}

const createAuthSlice = (set): AuthSlice => ({
  user: null,
  isAuthenticated: false,
  login: (user) => set({ user, isAuthenticated: true }),
  logout: () => set({ user: null, isAuthenticated: false }),
});

// UI 切片
interface UISlice {
  sidebarOpen: boolean;
  toggleSidebar: () => void;
}

const createUISlice = (set): UISlice => ({
  sidebarOpen: true,
  toggleSidebar: () =>
    set((state) => ({ sidebarOpen: !state.sidebarOpen })),
});

// 组合后的 Store
type AppState = AuthSlice & UISlice;

export const useAppStore = create<AppState>()((...a) => ({
  ...createAuthSlice(...a),
  ...createUISlice(...a),
}));

Computed Values

计算值

Derive values from state:
tsx
interface CartState {
  items: CartItem[];
  addItem: (item: CartItem) => void;
  removeItem: (id: string) => void;
  // Computed value as function
  total: () => number;
  itemCount: () => number;
}

export const useCartStore = create<CartState>((set, get) => ({
  items: [],
  addItem: (item) =>
    set((state) => ({ items: [...state.items, item] })),
  removeItem: (id) =>
    set((state) => ({
      items: state.items.filter((item) => item.id !== id),
    })),
  total: () => {
    return get().items.reduce((sum, item) => sum + item.price, 0);
  },
  itemCount: () => get().items.length,
}));

// Usage
function CartSummary() {
  const total = useCartStore((state) => state.total());
  const itemCount = useCartStore((state) => state.itemCount());

  return <div>Total: ${total} ({itemCount} items)</div>;
}
从状态中派生值：
tsx
interface CartState {
  items: CartItem[];
  addItem: (item: CartItem) => void;
  removeItem: (id: string) => void;
  // 作为函数的计算值
  total: () => number;
  itemCount: () => number;
}

export const useCartStore = create<CartState>((set, get) => ({
  items: [],
  addItem: (item) =>
    set((state) => ({ items: [...state.items, item] })),
  removeItem: (id) =>
    set((state) => ({
      items: state.items.filter((item) => item.id !== id),
    })),
  total: () => {
    return get().items.reduce((sum, item) => sum + item.price, 0);
  },
  itemCount: () => get().items.length,
}));

// 使用示例
function CartSummary() {
  const total = useCartStore((state) => state.total());
  const itemCount = useCartStore((state) => state.itemCount());

  return <div>Total: ${total} ({itemCount} items)</div>;
}

Selectors

选择器

Optimized Selectors

优化后的选择器

Prevent unnecessary re-renders:
tsx
import { useCartStore } from '@/stores/cart';
import { shallow } from 'zustand/shallow';

// Bad: Entire store subscribed
function BadComponent() {
  const store = useCartStore();
  return <div>{store.items.length}</div>;
}

// Good: Only subscribe to needed value
function GoodComponent() {
  const itemCount = useCartStore((state) => state.items.length);
  return <div>{itemCount}</div>;
}

// Better: Multiple values with shallow comparison
function BetterComponent() {
  const { items, addItem } = useCartStore(
    (state) => ({ items: state.items, addItem: state.addItem }),
    shallow
  );

  return <div>{items.length}</div>;
}
避免不必要的重渲染：
tsx
import { useCartStore } from '@/stores/cart';
import { shallow } from 'zustand/shallow';

// 不好的写法：订阅整个 Store
function BadComponent() {
  const store = useCartStore();
  return <div>{store.items.length}</div>;
}

// 好的写法：仅订阅需要的值
function GoodComponent() {
  const itemCount = useCartStore((state) => state.items.length);
  return <div>{itemCount}</div>;
}

// 更好的写法：使用浅层比较订阅多个值
function BetterComponent() {
  const { items, addItem } = useCartStore(
    (state) => ({ items: state.items, addItem: state.addItem }),
    shallow
  );

  return <div>{items.length}</div>;
}

Custom Selectors

自定义选择器

tsx
// stores/selectors.ts
import { useUserStore } from './user';

export const useIsAdmin = () =>
  useUserStore((state) => state.user?.role === 'admin');

export const useUserName = () =>
  useUserStore((state) => state.user?.name ?? 'Guest');

export const useHasPermission = (permission: string) =>
  useUserStore((state) =>
    state.user?.permissions.includes(permission)
  );

// Usage
function AdminPanel() {
  const isAdmin = useIsAdmin();
  if (!isAdmin) return null;
  return <div>Admin Panel</div>;
}
tsx
// stores/selectors.ts
import { useUserStore } from './user';

export const useIsAdmin = () =>
  useUserStore((state) => state.user?.role === 'admin');

export const useUserName = () =>
  useUserStore((state) => state.user?.name ?? 'Guest');

export const useHasPermission = (permission: string) =>
  useUserStore((state) =>
    state.user?.permissions.includes(permission)
  );

// 使用示例
function AdminPanel() {
  const isAdmin = useIsAdmin();
  if (!isAdmin) return null;
  return <div>Admin Panel</div>;
}

Async Actions

异步操作

Fetch Data

获取数据

tsx
interface PostsState {
  posts: Post[];
  isLoading: boolean;
  error: string | null;
  fetchPosts: () => Promise<void>;
}

export const usePostsStore = create<PostsState>((set) => ({
  posts: [],
  isLoading: false,
  error: null,
  fetchPosts: async () => {
    set({ isLoading: true, error: null });
    try {
      const response = await fetch('/api/posts');
      const posts = await response.json();
      set({ posts, isLoading: false });
    } catch (error) {
      set({ error: error.message, isLoading: false });
    }
  },
}));

// Usage
function PostList() {
  const { posts, isLoading, error, fetchPosts } = usePostsStore();

  useEffect(() => {
    fetchPosts();
  }, [fetchPosts]);

  if (isLoading) return <Loading />;
  if (error) return <Error message={error} />;
  return <div>{posts.map((post) => <PostCard post={post} />)}</div>;
}
tsx
interface PostsState {
  posts: Post[];
  isLoading: boolean;
  error: string | null;
  fetchPosts: () => Promise<void>;
}

export const usePostsStore = create<PostsState>((set) => ({
  posts: [],
  isLoading: false,
  error: null,
  fetchPosts: async () => {
    set({ isLoading: true, error: null });
    try {
      const response = await fetch('/api/posts');
      const posts = await response.json();
      set({ posts, isLoading: false });
    } catch (error) {
      set({ error: error.message, isLoading: false });
    }
  },
}));

// 使用示例
function PostList() {
  const { posts, isLoading, error, fetchPosts } = usePostsStore();

  useEffect(() => {
    fetchPosts();
  }, [fetchPosts]);

  if (isLoading) return <Loading />;
  if (error) return <Error message={error} />;
  return <div>{posts.map((post) => <PostCard post={post} />)}</div>;
}

Middleware

中间件

Persist

持久化

Persist state to localStorage:
tsx
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

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

export const usePreferencesStore = create<UserPreferences>()(
  persist(
    (set) => ({
      theme: 'light',
      language: 'en',
      setTheme: (theme) => set({ theme }),
      setLanguage: (language) => set({ language }),
    }),
    {
      name: 'user-preferences', // localStorage key
      storage: createJSONStorage(() => localStorage),
      partialize: (state) => ({
        theme: state.theme,
        language: state.language,
      }), // Only persist these fields
    }
  )
);
将状态持久化到 localStorage：
tsx
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

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

export const usePreferencesStore = create<UserPreferences>()(
  persist(
    (set) => ({
      theme: 'light',
      language: 'en',
      setTheme: (theme) => set({ theme }),
      setLanguage: (language) => set({ language }),
    }),
    {
      name: 'user-preferences', // localStorage 键名
      storage: createJSONStorage(() => localStorage),
      partialize: (state) => ({
        theme: state.theme,
        language: state.language,
      }), // 仅持久化这些字段
    }
  )
);

Devtools

开发者工具

Redux DevTools integration:
tsx
import { create } from 'zustand';
import { devtools } from 'zustand/middleware';

export const useAppStore = create<AppState>()(
  devtools(
    (set) => ({
      count: 0,
      increment: () => set((state) => ({ count: state.count + 1 }), false, 'increment'),
      decrement: () => set((state) => ({ count: state.count - 1 }), false, 'decrement'),
    }),
    { name: 'AppStore' }
  )
);
Redux DevTools 集成：
tsx
import { create } from 'zustand';
import { devtools } from 'zustand/middleware';

export const useAppStore = create<AppState>()(
  devtools(
    (set) => ({
      count: 0,
      increment: () => set((state) => ({ count: state.count + 1 }), false, 'increment'),
      decrement: () => set((state) => ({ count: state.count - 1 }), false, 'decrement'),
    }),
    { name: 'AppStore' }
  )
);

Immer

Immer

Use Immer for immutable updates:
tsx
import { create } from 'zustand';
import { immer } from 'zustand/middleware/immer';

interface TodoState {
  todos: Todo[];
  addTodo: (text: string) => void;
  toggleTodo: (id: string) => void;
}

export const useTodoStore = create<TodoState>()(
  immer((set) => ({
    todos: [],
    addTodo: (text) =>
      set((state) => {
        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;
      }),
  }))
);
使用 Immer 进行不可变更新：
tsx
import { create } from 'zustand';
import { immer } from 'zustand/middleware/immer';

interface TodoState {
  todos: Todo[];
  addTodo: (text: string) => void;
  toggleTodo: (id: string) => void;
}

export const useTodoStore = create<TodoState>()(
  immer((set) => ({
    todos: [],
    addTodo: (text) =>
      set((state) => {
        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;
      }),
  }))
);

Combined Middleware

组合中间件

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

export const useStore = create<State>()(
  devtools(
    persist(
      immer((set) => ({
        // store implementation
      })),
      { name: 'app-storage' }
    ),
    { name: 'AppStore' }
  )
);
tsx
import { create } from 'zustand';
import { devtools, persist } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';

export const useStore = create<State>()(
  devtools(
    persist(
      immer((set) => ({
        // store 实现
      })),
      { name: 'app-storage' }
    ),
    { name: 'AppStore' }
  )
);

Store Organization

Store 组织

Structure

结构

stores/
├── index.ts              # Export all stores
├── auth-store.ts         # Authentication state
├── cart-store.ts         # Shopping cart
├── ui-store.ts           # UI state (modals, sidebar, etc.)
├── preferences-store.ts  # User preferences
└── selectors/
    ├── auth-selectors.ts
    └── cart-selectors.ts
stores/
├── index.ts              # 导出所有 Store
├── auth-store.ts         # 认证状态
├── cart-store.ts         # 购物车
├── ui-store.ts           # UI 状态（模态框、侧边栏等）
├── preferences-store.ts  # 用户偏好
└── selectors/
    ├── auth-selectors.ts
    └── cart-selectors.ts

Index File

索引文件

tsx
// stores/index.ts
export { useAuthStore } from './auth-store';
export { useCartStore } from './cart-store';
export { useUIStore } from './ui-store';
export { usePreferencesStore } from './preferences-store';
tsx
// stores/index.ts
export { useAuthStore } from './auth-store';
export { useCartStore } from './cart-store';
export { useUIStore } from './ui-store';
export { usePreferencesStore } from './preferences-store';

TypeScript Patterns

TypeScript 模式

Typed Actions

类型化操作

tsx
interface UserState {
  user: User | null;
  status: 'idle' | 'loading' | 'success' | 'error';
  error: string | null;
  setUser: (user: User) => void;
  clearUser: () => void;
  fetchUser: (id: string) => Promise<void>;
}

export const useUserStore = create<UserState>((set) => ({
  user: null,
  status: 'idle',
  error: null,
  setUser: (user) => set({ user, status: 'success', error: null }),
  clearUser: () => set({ user: null, status: 'idle', error: null }),
  fetchUser: async (id) => {
    set({ status: 'loading' });
    try {
      const user = await api.fetchUser(id);
      set({ user, status: 'success', error: null });
    } catch (error) {
      set({ status: 'error', error: error.message });
    }
  },
}));
tsx
interface UserState {
  user: User | null;
  status: 'idle' | 'loading' | 'success' | 'error';
  error: string | null;
  setUser: (user: User) => void;
  clearUser: () => void;
  fetchUser: (id: string) => Promise<void>;
}

export const useUserStore = create<UserState>((set) => ({
  user: null,
  status: 'idle',
  error: null,
  setUser: (user) => set({ user, status: 'success', error: null }),
  clearUser: () => set({ user: null, status: 'idle', error: null }),
  fetchUser: async (id) => {
    set({ status: 'loading' });
    try {
      const user = await api.fetchUser(id);
      set({ user, status: 'success', error: null });
    } catch (error) {
      set({ status: 'error', error: error.message });
    }
  },
}));

Testing

测试

Test Setup

测试设置

tsx
// __tests__/stores/counter.test.ts
import { renderHook, act } from '@testing-library/react';
import { useCounterStore } from '@/stores/counter';

describe('useCounterStore', () => {
  beforeEach(() => {
    // Reset store before each test
    useCounterStore.setState({ count: 0 });
  });

  it('increments count', () => {
    const { result } = renderHook(() => useCounterStore());

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

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

  it('decrements count', () => {
    const { result } = renderHook(() => useCounterStore());

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

    expect(result.current.count).toBe(-1);
  });
});
tsx
// __tests__/stores/counter.test.ts
import { renderHook, act } from '@testing-library/react';
import { useCounterStore } from '@/stores/counter';

describe('useCounterStore', () => {
  beforeEach(() => {
    // 每次测试前重置 Store
    useCounterStore.setState({ count: 0 });
  });

  it('increments count', () => {
    const { result } = renderHook(() => useCounterStore());

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

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

  it('decrements count', () => {
    const { result } = renderHook(() => useCounterStore());

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

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

Best Practices

最佳实践

Do

建议

  • Keep stores focused on specific domains
  • Use selectors to prevent unnecessary re-renders
  • Use middleware for cross-cutting concerns
  • Type all stores with TypeScript
  • Extract complex logic to separate functions
  • Use shallow comparison for object selections
  • Persist only necessary state
  • 保持 Store 聚焦于特定领域
  • 使用选择器避免不必要的重渲染
  • 使用中间件处理横切关注点
  • 为所有 Store 添加 TypeScript 类型
  • 将复杂逻辑提取到独立函数中
  • 对对象选择使用浅层比较
  • 仅持久化必要的状态

Don't

不建议

  • Don't put all state in one store
  • Don't select entire store when only part is needed
  • Don't mutate state directly (use set or Immer)
  • Don't use Zustand for server state (use React Query)
  • Don't persist sensitive data
  • Don't forget to reset state when needed
  • 不要将所有状态放入单个 Store
  • 不要在只需要部分状态时选择整个 Store
  • 不要直接修改状态（使用 set 或 Immer）
  • 不要使用 Zustand 管理服务端状态（使用 React Query）
  • 不要持久化敏感数据
  • 必要时不要忘记重置状态

When to Use

使用场景

Use Zustand

使用 Zustand

  • Client-side UI state (modals, sidebar, theme)
  • Form state (multi-step forms)
  • Global app state (user preferences, settings)
  • Temporary state shared across components
  • 客户端 UI 状态（模态框、侧边栏、主题）
  • 表单状态（多步骤表单）
  • 全局应用状态（用户偏好、设置）
  • 跨组件共享的临时状态

Use React Query

使用 React Query

  • Server state (API data)
  • Caching and revalidation
  • Background updates
  • Optimistic updates with server sync
  • 服务端状态（API 数据）
  • 缓存和重新验证
  • 后台更新
  • 与服务端同步的乐观更新

Use React State

使用 React 内置状态

  • Local component state
  • Form inputs
  • Toggle states
  • State not shared with other components
  • 本地组件状态
  • 表单输入
  • 切换状态
  • 不与其他组件共享的状态

Performance

性能

Optimization

优化

  • Use selective subscriptions (don't select entire store)
  • Use shallow comparison for object selections
  • Batch updates when possible
  • Split large stores into smaller, focused stores
  • Use computed values (functions) instead of derived state
  • 使用选择性订阅（不要选择整个 Store）
  • 对对象选择使用浅层比较
  • 尽可能批量更新
  • 将大型 Store 拆分为更小的、聚焦的 Store
  • 使用计算值（函数）而非派生状态

Monitoring

监控

  • Use Redux DevTools middleware in development
  • Monitor render counts in React DevTools
  • Profile component re-renders
  • Check localStorage size if using persist
  • 在开发环境中使用 Redux DevTools 中间件
  • 在 React DevTools 中监控渲染次数
  • 分析组件重渲染情况
  • 如果使用持久化，检查 localStorage 大小