react-state

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zustand for React

适用于React的Zustand

Minimal, scalable state management with React 18+ useSyncExternalStore.

基于React 18+ useSyncExternalStore的轻量级、可扩展状态管理方案。

Agent Workflow (MANDATORY)

Agent工作流（必填）

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Analyze existing stores and state patterns
fuse-ai-pilot:research-expert - Verify latest Zustand v5 docs via Context7/Exa
mcp__context7__query-docs - Check middleware and TypeScript patterns

After implementation, run fuse-ai-pilot:sniper for validation.

在进行任何实现之前，使用

TeamCreate

生成3个Agent：

fuse-ai-pilot:explore-codebase - 分析现有状态存储和状态模式
fuse-ai-pilot:research-expert - 通过Context7/Exa验证最新的Zustand v5文档
mcp__context7__query-docs - 检查中间件和TypeScript模式

实现完成后，运行fuse-ai-pilot:sniper进行验证。

Overview

概述

When to Use

适用场景

Managing global state in React applications
Need state shared across components
Persisting state to localStorage/sessionStorage
Building UI state (modals, sidebars, theme, cart)
Replacing React Context for complex state

在React应用中管理全局状态
需要跨组件共享状态
将状态持久化到localStorage/sessionStorage
构建UI状态（模态框、侧边栏、主题、购物车）
替代React Context处理复杂状态

Why Zustand v5

选择Zustand v5的原因

Feature	Benefit
Minimal API	Simple create() function, no boilerplate
React 18 native	useSyncExternalStore, no shims needed
TypeScript first	Full inference with currying pattern
Middleware stack	devtools, persist, immer composable
Bundle size	~2KB gzipped, smallest state library
No providers	Direct store access, no Context wrapper

特性	优势
极简API	仅需简单的create()函数，无冗余模板代码
原生支持React 18	基于useSyncExternalStore，无需垫片
优先支持TypeScript	通过柯里化模式实现完整类型推断
中间件栈	devtools、persist、immer可组合使用
包体积	压缩后约2KB，体积最小的状态管理库之一
无需Provider	直接访问状态存储，无需Context包裹

Critical Rules

关键规则

useShallow for arrays/objects - Prevent unnecessary re-renders
Currying syntax v5 -
```
create<State>()((set) => ({...}))
```
SOLID paths - Stores in
```
modules/[feature]/src/stores/
```
Separate stores - One store per domain (auth, cart, ui, theme)
Server state elsewhere - Use TanStack Query for server state

对数组/对象使用useShallow - 避免不必要的重渲染
v5柯里化语法 -
```
create<State>()((set) => ({...}))
```
SOLID路径规范 - 状态存储放在
```
modules/[feature]/src/stores/
```
目录下
拆分状态存储 - 每个领域对应一个状态存储（认证、购物车、UI、主题）
服务端状态单独处理 - 使用TanStack Query管理服务端状态

SOLID Architecture

SOLID架构

Module Structure

模块结构

Stores organized by feature module:

```
modules/cores/stores/
```
- Shared stores (theme, ui)
```
modules/auth/src/stores/
```
- Auth state
```
modules/cart/src/stores/
```
- Cart state
```
modules/[feature]/src/interfaces/
```
- Store types

状态存储按功能模块组织：

```
modules/cores/stores/
```
- 共享状态存储（主题、UI）
```
modules/auth/src/stores/
```
- 认证状态
```
modules/cart/src/stores/
```
- 购物车状态
```
modules/[feature]/src/interfaces/
```
- 状态存储类型定义

File Organization

文件组织

File	Purpose	Max Lines
`store.ts`	Store creation with create()	50
`store.interface.ts`	TypeScript interfaces	30
`use-store.ts`	Custom hook with selector	20

文件	用途	最大行数
`store.ts`	使用create()创建状态存储	50
`store.interface.ts`	TypeScript接口定义	30
`use-store.ts`	带选择器的自定义Hook	20

Key Concepts

核心概念

Store Creation (v5 Syntax)

状态存储创建（v5语法）

Double parentheses required for TypeScript inference. Currying pattern ensures full type safety.

需要双层括号以实现TypeScript类型推断。柯里化模式确保完整的类型安全。

Middleware Composition

中间件组合

Stack middlewares: devtools -> persist -> immer. Order matters for TypeScript types.

按顺序堆叠中间件：devtools -> persist -> immer。顺序会影响TypeScript类型。

Selector Pattern

选择器模式

Always use

useStore((s) => s.field)

for performance. Use

useShallow

for array/object selectors.

始终使用

useStore((s) => s.field)

以保证性能。对数组/对象选择器使用

useShallow

。

Reference Guide

参考指南

Need	Reference
Initial setup	installation.md
Store patterns	store-patterns.md
Middleware	middleware.md
TypeScript	typescript.md
Slices pattern	slices.md
Auto selectors	auto-selectors.md
Reset state	reset-state.md
Subscribe API	subscribe-api.md
Testing	testing.md
Migration v4→v5	migration-v5.md

需求	参考文档
初始设置	installation.md
状态存储模式	store-patterns.md
中间件	middleware.md
TypeScript相关	typescript.md
切片模式	slices.md
自动选择器	auto-selectors.md
重置状态	reset-state.md
订阅API	subscribe-api.md
测试	testing.md
从v4迁移到v5	migration-v5.md

Best Practices

最佳实践

Selector pattern - Always use
```
useStore((s) => s.field)
```
for performance
useShallow - Wrap array/object selectors to prevent re-renders
Separate stores - One store per domain (auth, cart, ui, theme)
Server data elsewhere - Use TanStack Query for server state
DevTools in dev only - Wrap devtools in process.env check
Partialize persist - Only persist necessary fields, never tokens

选择器模式 - 始终使用
```
useStore((s) => s.field)
```
以保证性能
useShallow的使用 - 对数组/对象选择器使用
```
useShallow
```
以避免重渲染
拆分状态存储 - 每个领域对应一个状态存储（认证、购物车、UI、主题）
服务端数据单独处理 - 使用TanStack Query管理服务端状态
仅在开发环境使用DevTools - 用process.env判断包裹devtools
部分持久化 - 仅持久化必要字段，绝不持久化令牌

Forbidden Patterns

禁用模式

Pattern	Reason	Alternative
Persisting auth tokens	Security vulnerability	httpOnly cookies
Without useShallow on objects	Excessive re-renders	`useShallow(selector)`
v4 syntax	TypeScript inference broken	v5 currying `create<T>()()`
Giant monolithic store	Hard to maintain	Slices or separate stores

模式	原因	替代方案
持久化认证令牌	存在安全漏洞	使用httpOnly cookies
对对象不使用useShallow	导致过度重渲染	`useShallow(selector)`
v4语法	破坏TypeScript类型推断	v5柯里化语法 `create<T>()()`
巨型单体状态存储	难以维护	使用切片或拆分状态存储