superpower-zustand

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zustand StoreBuilder Pattern

Zustand StoreBuilder 模式

<CRITICAL> DO NOT create Zustand stores using standard patterns (create with inline actions). ALL Zustand stores in this project MUST use the StoreBuilder pattern defined below. This is a required architectural standard, not a suggestion. </CRITICAL>

<CRITICAL> 禁止使用标准模式（带内联actions的create方法）创建Zustand store。本项目中所有Zustand store必须使用以下定义的StoreBuilder模式。这是强制的架构标准，而非建议。 </CRITICAL>

Purpose

目的

Enforce a standardized, type-safe approach to creating Zustand stores that:

Separates state definition from actions using the factory pattern
Integrates immer middleware for convenient immutable updates
Supports optional persistence with fine-grained control
Exposes both reactive (useStore hook) and non-reactive (get/set) access
Maintains consistent patterns across the codebase

实施标准化、类型安全的Zustand store创建方式，实现：

使用工厂模式分离状态定义与actions
集成immer中间件，便捷实现不可变更新
支持可选的持久化，且可进行细粒度控制
同时提供响应式（useStore钩子）和非响应式（get/set）访问方式
维持代码库中模式的一致性

When to Use This Skill

何时使用此技能

Use this skill when:

Creating new Zustand stores for state management
User requests state management solutions in a React application
Implementing stores for any feature requiring client-side state

在以下场景使用此技能：

为状态管理创建新的Zustand store
用户请求React应用中的状态管理解决方案
为任何需要客户端状态的功能实现store

Required Pattern

要求的模式

All Zustand stores MUST use the StoreBuilder utility located in

assets/storebuilder.ts

所有Zustand store必须使用位于

assets/storebuilder.ts

中的StoreBuilder工具。

Core Implementation Steps

核心实施步骤

Copy the StoreBuilder utility (if not already in the project)
- Source:
```
skills/superpower-zustand/assets/storebuilder.ts
```
- Destination:
```
src/lib/storebuilder.ts
```
  (or similar location in the project)
Define state type separately from actions
- Create a type for the full store (state + actions)
- Use
```
Omit
```
  to exclude action methods when passing to StoreBuilder
Initialize the store with StoreBuilder
- Pass initial state as first argument
- Optionally pass PersistConfig as second argument for persistence
Separate actions using createFactory
- Define all actions as methods in the createFactory argument
- Actions access
```
set
```
  from the StoreBuilder closure
- Use immer-style mutations within
```
set
```
  callbacks
Export the factory-created hook
- The hook returned by createFactory combines state, actions, and store utilities

复制StoreBuilder工具（如果项目中尚未存在）
- 来源：
```
skills/superpower-zustand/assets/storebuilder.ts
```
- 目标位置：
```
src/lib/storebuilder.ts
```
  （或项目中的类似位置）
单独定义状态类型与actions
- 为完整的store（状态+actions）创建类型
- 传递给StoreBuilder时，使用
```
Omit
```
  排除action方法
使用StoreBuilder初始化store
- 第一个参数传入初始状态
- 第二个参数可选传入PersistConfig以实现持久化
使用createFactory分离actions
- 在createFactory的参数中，将所有actions定义为方法
- Actions从StoreBuilder闭包中访问
```
set
```
- 在
```
set
```
  回调中使用immer风格的变更
导出工厂创建的钩子
- createFactory返回的钩子结合了状态、actions和store工具

Required Code Structure

要求的代码结构

typescript

import { StoreBuilder } from './storebuilder';

// 1. Define complete state type
type MyStoreState = {
  // State fields
  value: number;
  items: string[];

  // Action methods
  setValue: (v: number) => void;
  addItem: (item: string) => void;
};

// 2. Initialize StoreBuilder with state only (Omit actions)
const { set, createFactory } = StoreBuilder<Omit<MyStoreState, 'setValue' | 'addItem'>>(
  {
    value: 0,
    items: [],
  },
  // Optional: persistence config
  // {
  //   name: 'my-store',
  //   version: 1,
  // }
);

// 3. Create factory with actions
const useMyStore = createFactory({
  setValue: (v: number) => set((state) => { state.value = v; }),
  addItem: (item: string) => set((state) => { state.items.push(item); }),
});

// 4. Export the hook
export { useMyStore };

typescript

import { StoreBuilder } from './storebuilder';

// 1. Define complete state type
type MyStoreState = {
  // State fields
  value: number;
  items: string[];

  // Action methods
  setValue: (v: number) => void;
  addItem: (item: string) => void;
};

// 2. Initialize StoreBuilder with state only (Omit actions)
const { set, createFactory } = StoreBuilder<Omit<MyStoreState, 'setValue' | 'addItem'>>(
  {
    value: 0,
    items: [],
  },
  // Optional: persistence config
  // {
  //   name: 'my-store',
  //   version: 1,
  // }
);

// 3. Create factory with actions
const useMyStore = createFactory({
  setValue: (v: number) => set((state) => { state.value = v; }),
  addItem: (item: string) => set((state) => { state.items.push(item); }),
});

// 4. Export the hook
export { useMyStore };

State Updates with Immer

使用Immer进行状态更新

When using

set

, write mutations directly on the draft state (immer middleware is included):

typescript

// ✅ Correct: Mutate draft
set((state) => {
  state.count += 1;
  state.items.push(newItem);
  state.nested.property = 'value';
});

// ❌ Incorrect: Don't return new object
set((state) => ({ ...state, count: state.count + 1 }));

使用

set

时，直接在draft状态上进行变更（已包含immer中间件）：

typescript

// ✅ Correct: Mutate draft
set((state) => {
  state.count += 1;
  state.items.push(newItem);
  state.nested.property = 'value';
});

// ❌ Incorrect: Don't return new object
set((state) => ({ ...state, count: state.count + 1 }));

Persistence Configuration

持久化配置

When state should persist across sessions:

typescript

const { createFactory } = StoreBuilder(
  initialState,
  {
    name: 'storage-key',           // Required: localStorage key
    version: 1,                     // Optional: for migration handling
    storage: sessionStorage,        // Optional: defaults to localStorage
    partialize: (state) => ({       // Optional: persist only specific fields
      theme: state.theme,
      preferences: state.preferences,
    }),
  }
);

当状态需要跨会话持久化时：

typescript

const { createFactory } = StoreBuilder(
  initialState,
  {
    name: 'storage-key',           // Required: localStorage key
    version: 1,                     // Optional: for migration handling
    storage: sessionStorage,        // Optional: defaults to localStorage
    partialize: (state) => ({       // Optional: persist only specific fields
      theme: state.theme,
      preferences: state.preferences,
    }),
  }
);

Reference Documentation

参考文档

For detailed examples and advanced patterns, read

references/pattern-guide.md

Basic usage examples
Persistence patterns
Complex stores with async actions
Using get/set outside React components
Type safety patterns

Load the reference documentation when:

Implementing complex stores with async operations
Needing examples of persistence configuration
User asks about advanced Zustand patterns
Unsure about specific implementation details

如需详细示例和高级模式，请阅读

references/pattern-guide.md

：

基础使用示例
持久化模式
带异步actions的复杂store
在React组件外使用get/set
类型安全模式

在以下场景加载参考文档：

实现带异步操作的复杂store
需要持久化配置的示例
用户询问Zustand高级模式
对具体实现细节不确定时

Verification

验证

After creating a store, verify:

✅ StoreBuilder utility is imported from project location
✅ State type uses
```
Omit
```
to exclude actions
✅ All actions are defined in
```
createFactory
```
, not in initial state
✅ State updates use immer-style mutations (mutate draft, don't return new object)
✅ Exported hook name follows convention (e.g.,
```
useMyStore
```
)
✅ Persistence config is included if state should persist

创建store后，验证以下内容：

✅ StoreBuilder工具从项目位置导入
✅ 状态类型使用
```
Omit
```
排除actions
✅ 所有actions定义在
```
createFactory
```
中，而非初始状态
✅ 状态更新使用immer风格的变更（修改draft，不返回新对象）
✅ 导出的钩子名称遵循约定（例如
```
useMyStore
```
）
✅ 如果状态需要持久化，已包含持久化配置

Non-React Usage

非React场景使用

The pattern supports non-reactive access outside React components:

typescript

const { get, set, subscribe } = StoreBuilder(initialState);

// Get current state
const current = get();

// Update state
set((state) => { state.value = 10; });

// Subscribe to changes
const unsubscribe = subscribe((state) => console.log(state));

Use

get

and

set

when:

Accessing state in utility functions
Implementing middleware or side effects
Working outside React component lifecycle

该模式支持在React组件外进行非响应式访问：

typescript

const { get, set, subscribe } = StoreBuilder(initialState);

// Get current state
const current = get();

// Update state
set((state) => { state.value = 10; });

// Subscribe to changes
const unsubscribe = subscribe((state) => console.log(state));

在以下场景使用

get

和

set

：

在工具函数中访问状态
实现中间件或副作用
在React组件生命周期外工作