zustand

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Community Zustand Best Practices

社区版Zustand最佳实践

Comprehensive performance and architecture guide for Zustand state management in React applications. Contains 43 rules across 8 categories, prioritized by impact from critical (store architecture, selector optimization) to incremental (advanced patterns).

这是一份针对React应用中Zustand状态管理的全面性能与架构指南。包含8个类别共43条规则，按影响优先级排序，从关键级别（store架构、选择器优化）到增量级别（高级模式）。

When to Apply

适用场景

Reference these guidelines when:

Creating new Zustand stores
Optimizing re-render performance with selectors
Implementing persistence or middleware
Integrating Zustand with SSR/Next.js
Reviewing code for state management patterns

在以下场景中可参考本指南：

创建新的Zustand store
使用选择器优化重渲染性能
实现持久化或中间件
将Zustand与SSR/Next.js集成
评审状态管理模式相关代码

Rule Categories by Priority

按优先级划分的规则类别


store-
select-
render-
update-
mw-
ssr-
ts-
adv-

Priority	Category	Impact	Prefix
1	Store Architecture	CRITICAL	`store-`
2	Selector Optimization	CRITICAL	`select-`
3	Re-render Prevention	HIGH	`render-`
4	State Updates	MEDIUM-HIGH	`update-`
5	Middleware Configuration	MEDIUM	`mw-`
6	SSR and Hydration	MEDIUM	`ssr-`
7	TypeScript Patterns	LOW-MEDIUM	`ts-`
8	Advanced Patterns	LOW	`adv-`


store-
select-
render-
update-
mw-
ssr-
ts-
adv-

优先级	类别	影响级别	前缀
1	Store架构	关键	`store-`
2	选择器优化	关键	`select-`
3	重渲染预防	高	`render-`
4	状态更新	中高	`update-`
5	中间件配置	中	`mw-`
6	SSR与水合	中	`ssr-`
7	TypeScript模式	中低	`ts-`
8	高级模式	低	`adv-`

Quick Reference

快速参考

1. Store Architecture (CRITICAL)

1. Store架构（关键）

```
store-multiple-stores
```
- Use multiple small stores instead of one monolithic store
```
store-separate-actions
```
- Separate actions from state in dedicated namespace
```
store-event-naming
```
- Name actions as events not setters
```
store-colocate-logic
```
- Colocate actions with the state they modify
```
store-avoid-derived-state
```
- Derive computed values instead of storing them
```
store-domain-boundaries
```
- Organize stores by feature domain

```
store-multiple-stores
```
- 使用多个小型store替代单一大型store
```
store-separate-actions
```
- 在独立命名空间中将操作与状态分离
```
store-event-naming
```
- 操作命名采用事件而非设置器形式
```
store-colocate-logic
```
- 将操作与它们修改的状态放在一起
```
store-avoid-derived-state
```
- 推导计算值而非直接存储
```
store-domain-boundaries
```
- 按功能领域组织store

2. Selector Optimization (CRITICAL)

2. 选择器优化（关键）

```
select-always-use
```
- Always use selectors never subscribe to entire store
```
select-atomic-picks
```
- Use atomic selectors for single values
```
select-stable-returns
```
- Ensure selectors return stable references
```
select-custom-hooks
```
- Export custom hooks not raw store
```
select-auto-generate
```
- Use auto-generated selectors for large stores
```
select-memoize-computed
```
- Memoize expensive computed selectors
```
select-avoid-inline
```
- Define selectors outside components

```
select-always-use
```
- 始终使用选择器，绝不订阅整个store
```
select-atomic-picks
```
- 对单一值使用原子选择器
```
select-stable-returns
```
- 确保选择器返回稳定的引用
```
select-custom-hooks
```
- 导出自定义钩子而非原始store
```
select-auto-generate
```
- 对大型store使用自动生成的选择器
```
select-memoize-computed
```
- 对开销大的计算选择器进行记忆化
```
select-avoid-inline
```
- 在组件外部定义选择器

3. Re-render Prevention (HIGH)

3. 重渲染预防（高）

```
render-use-shallow
```
- Use useShallow for multi-property selections
```
render-equality-fn
```
- Provide custom equality functions when needed
```
render-memo-children
```
- Memo children affected by parent store updates
```
render-subscribe-external
```
- Use subscribe for non-React consumers
```
render-avoid-object-returns
```
- Avoid returning new objects from selectors
```
render-split-components
```
- Split components to minimize subscription scope

```
render-use-shallow
```
- 对多属性选择使用useShallow
```
render-equality-fn
```
- 必要时提供自定义相等性函数
```
render-memo-children
```
- 对受父store更新影响的子组件进行记忆化
```
render-subscribe-external
```
- 对非React消费者使用subscribe
```
render-avoid-object-returns
```
- 避免从选择器返回新对象
```
render-split-components
```
- 拆分组件以最小化订阅范围

4. State Updates (MEDIUM-HIGH)

4. 状态更新（中高）

```
update-functional-set
```
- Use functional form when updating based on previous state
```
update-immutable
```
- Never mutate state directly
```
update-shallow-merge
```
- Understand set() shallow merge behavior
```
update-async-actions
```
- Handle async actions with loading and error states
```
update-batch-updates
```
- Batch related updates in single set call

```
update-functional-set
```
- 基于之前状态更新时使用函数式形式
```
update-immutable
```
- 绝不直接修改状态
```
update-shallow-merge
```
- 理解set()的浅合并行为
```
update-async-actions
```
- 处理异步操作时包含加载和错误状态
```
update-batch-updates
```
- 在单个set调用中批量处理相关更新

5. Middleware Configuration (MEDIUM)

5. 中间件配置（中）

```
mw-devtools-actions
```
- Name actions for DevTools debugging
```
mw-persist-partialize
```
- Use partialize for selective persistence
```
mw-persist-migration
```
- Version and migrate persisted state
```
mw-immer-nested
```
- Use immer for deeply nested state updates
```
mw-combine-order
```
- Apply middlewares in correct order
```
mw-slice-middleware
```
- Apply middleware at combined store level

```
mw-devtools-actions
```
- 为DevTools调试给操作命名
```
mw-persist-partialize
```
- 使用partialize实现选择性持久化
```
mw-persist-migration
```
- 对持久化状态进行版本控制和迁移
```
mw-immer-nested
```
- 使用Immer处理深度嵌套的状态更新
```
mw-combine-order
```
- 按正确顺序应用中间件
```
mw-slice-middleware
```
- 在组合store级别应用中间件

6. SSR and Hydration (MEDIUM)

6. SSR与水合（中）

```
ssr-skip-hydration
```
- Use skipHydration in SSR contexts
```
ssr-manual-rehydrate
```
- Manually rehydrate on client mount
```
ssr-hydration-hook
```
- Use custom hook to prevent hydration mismatch
```
ssr-check-window
```
- Guard browser APIs with typeof window check

```
ssr-skip-hydration
```
- 在SSR环境中使用skipHydration
```
ssr-manual-rehydrate
```
- 在客户端挂载时手动进行水合
```
ssr-hydration-hook
```
- 使用自定义钩子避免水合不匹配
```
ssr-check-window
```
- 用typeof window检查保护浏览器API

7. TypeScript Patterns (LOW-MEDIUM)

7. TypeScript模式（中低）

```
ts-state-creator
```
- Use StateCreator for slice typing
```
ts-middleware-inference
```
- Preserve type inference with middleware
```
ts-separate-types
```
- Separate state and actions interfaces
```
ts-generic-selectors
```
- Type selectors for reusability
```
ts-bound-store
```
- Type combined stores correctly

```
ts-state-creator
```
- 使用StateCreator进行切片类型定义
```
ts-middleware-inference
```
- 保留中间件的类型推断
```
ts-separate-types
```
- 分离状态和操作的接口
```
ts-generic-selectors
```
- 为选择器添加类型以提升复用性
```
ts-bound-store
```
- 正确为组合store添加类型

8. Advanced Patterns (LOW)

8. 高级模式（低）

```
adv-context-stores
```
- Combine Zustand with React Context for dependency injection
```
adv-transient-updates
```
- Use subscribe for transient updates
```
adv-computed-getters
```
- Implement computed state with getters
```
adv-third-party-integration
```
- Integrate with React Query and SWR

```
adv-context-stores
```
- 将Zustand与React Context结合实现依赖注入
```
adv-transient-updates
```
- 使用subscribe处理临时更新
```
adv-computed-getters
```
- 使用getter实现计算状态
```
adv-third-party-integration
```
- 与React Query和SWR集成

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

章节定义 - 类别结构和影响级别
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息