home / skills / forge-town / skills / store-best-practice

store-best-practice skill

safe

This skill helps you implement scalable, type-safe Zustand stores with slice architecture, provider setup, and clean exports for easy reuse.

npx playbooks add skill forge-town/skills --skill store-best-practice

Review the files below or copy the command above to add this skill to your agents.

Files (8)

SKILL.md

2.5 KB

---
name: store-best-practice
description: 使用 Zustand 或类似状态管理库生成最佳实践的 store 实现。当您需要创建可扩展、类型安全的 store 时使用，包括适当的 slice 模式和 provider 设置。
---

# Store 最佳实践

提供创建和管理状态管理store的最佳实践指导和模板。包含slice模式、store组合、类型安全、provider设置等示例和最佳实践。

## 工作原理

1. 分析应用状态需求，确定需要管理的状态切片
2. **严格参照** [best-practice-examples/](best-practice-examples/) 中的代码结构和模式
3. 为每个状态切片创建独立的 slice 文件
4. 创建主 store 文件组合所有 slices
5. 实现 provider 组件提供 store 上下文
6. 创建桶导出以实现干净的导入
7. 在应用程序中使用生成的 store

## 能力边界
1. **职责边界**：仅负责状态的存储、同步与修改，复杂业务逻辑（数据校验、格式转换、业务规则判断）需抽离为独立工具函数
2. **使用边界**：仅用于「跨组件/跨模块共享状态」，组件私有状态优先使用`useState`/`useReducer`，禁止过度使用store
3. **数据边界**：不存储临时/一次性数据（如单次请求的临时参数），仅存储需持久化或多次复用的状态

## 使用方法

此技能提供文档和示例。按照参考指南中的步骤操作：

- [Store 最佳实践指南](references/store-best-practice-guide.md) - Store 设计和实现的详细规则
- [最佳实践示例](best-practice-examples/) - **必须严格参照的** Zustand store 示例

**重要：** 实现时必须严格遵循 best-practice-examples 中的代码结构、命名约定和模式。任何修改都可能破坏类型安全和可维护性。

## 输出

技能将生成：
- 独立的 slice 文件（每个状态切片一个）
- 主 store 文件（组合所有 slices）
- Provider 组件（提供 store 上下文）
- 桶导出文件（index.ts）

**注意：** 调用完毕技能后，强制查看 [检查清单](checklist.md)，并确保返回的内容完全匹配清单中的所有项目。

## 故障排除

- **状态管理库未安装**：在项目中运行 `pnpm install zustand`
- **类型错误**：检查 slice 中的状态和动作类型定义
- **Provider 未正确设置**：确保在应用根组件中包装 Provider
- **状态不更新**：检查 slice 中的动作是否正确修改状态
- **偏离最佳实践**：如果遇到问题，首先确认代码结构是否严格遵循 best-practice-examples 中的模式

Overview

This skill generates TypeScript-ready Zustand (or similar) store implementations following proven best practices for scalability and type safety. It produces per-slice files, a combined root store, a Provider component, and clean barrel exports to keep imports predictable. The output is focused on predictable patterns, strong typings, and easy composition across modules.

How this skill works

The skill analyzes the desired application state surface and recommends a slice-per-concern structure. It scaffolds independent slice files with typed state and actions, composes them into a root store, and generates a Provider that injects the store into the app context. All code follows consistent naming, file layout, and type patterns to avoid runtime surprises and preserve IDE tooling support.

When to use it

When you need a scalable, type-safe global store for cross-component state sharing
When multiple features require shared state and clear boundaries between domains
When migrating from ad-hoc useState usage to a centralized store pattern
When you want consistent, reviewable store structure across a team
When you need a store that composes cleanly and supports testing

Best practices

Create one slice per domain or feature to keep responsibilities small and testable
Define strict TypeScript types for state and actions; export public interfaces only
Keep complex business logic out of slices—use pure utility functions and inject them where needed
Compose slices in a single root store file to centralize wiring and middleware
Provide a Provider to scope the store at the app root and use hooks for consumption
Export a barrel (index.ts) for predictable imports and easier refactors

Example use cases

User session slice + preferences slice combined into a single store for auth and UI defaults
Shopping cart slice with actions for mutations and selectors for derived totals
Feature flag slice that can be swapped or mocked during tests
Form wizard slices isolated per step, composed into a wizard store for cross-step navigation
Shared network request state slice to coordinate loading/error states across components

FAQ

Do I have to use Zustand specifically?

Zustand patterns are recommended, but the same slice/composition and typing principles apply to similar lightweight state libraries.

Where should I place complex validation or transformation logic?

Keep that logic in separate pure utility modules and call them from slice actions; slices should focus on state updates and synchronization.