SuperAPI AI 工具集

nextjs-zustand

前端与建站

查看项目

更新于 10-26 16:23

技能介绍

用途

nextjs-zustand 用于在 Next.js 16 App Router 的客户端组件中实现全局状态管理,基于 Zustand v5。适用场景包括:在 App Router 应用中管理客户端状态、需要在客户端组件之间共享全局状态、将状态持久化到 localStorage/sessionStorage、构建 UI 状态(模态框、侧边栏、主题、购物车),以及用 Zustand 替代 React Context 处理复杂状态。

主要能力

  • 使用 Zustand v5 的 create() 函数创建 store,采用柯里化语法 create<State>()((set) => ({...})) 以获得完整的 TypeScript 类型推断。
  • 通过 Context 模式在 App Router 中隔离 store,避免请求间共享;使用 zustand/vanilla 的 createStore 配合 useRef 进行初始化。
  • 中间件组合:按 devtools → persist → immer 的顺序堆叠,顺序影响 TypeScript 类型。
  • 持久化与 hydration:使用 persist 中间件的 skipHydration: true,并在 useEffect 中手动再水合,以避免 SSR 不匹配。
  • 选择器优化:使用 useShallow 包装数组/对象选择器,防止不必要的重渲染。
  • SOLID 文件组织:store.ts(创建 store,最多 40 行)、store.interface.ts(TypeScript 接口)、store-provider.tsx(Context provider)、use-store.ts(带选择器的自定义 hook)。
  • 按功能模块组织 store:modules/cores/stores/(共享 store,如 theme、ui)、modules/auth/src/stores/、modules/cart/src/stores/、modules/[feature]/src/interfaces/。

使用方式

技能文档要求在执行任何实现之前,并行启动 3 个 agent(每个 Agent 调用带一个名称):fuse-ai-pilot:explore-codebase 分析现有 store 和状态模式;fuse-ai-pilot:research-expert 通过 Context7/Exa 验证最新的 Zustand v5 文档;mcp__context7__query-docs 检查中间件和 TypeScript 模式。实现完成后,运行 fuse-ai-pilot:sniper 进行验证。

参考指南按需查阅:初始设置见 installation.md,store 模式见 store-patterns.md,SSR/Hydration 见 hydration.md,中间件见 middleware.md,Next.js App Router 集成见 nextjs-integration.md,TypeScript 见 typescript.md,slices 模式见 slices.md,自动选择器见 auto-selectors.md,重置状态见 reset-state.md,Subscribe API 见 subscribe-api.md,测试见 testing.md,v4→v5 迁移见 migration-v5.md。

关键规则与最佳实践

  • Zustand 仅用于客户端组件,绝不在服务端组件中使用;服务端组件应直接获取数据。
  • App Router 使用 Context 模式,避免全局 store(请求隔离)。
  • 数组/对象选择器使用 useShallow,防止不必要的重渲染。
  • persist 必须配合 skipHydration 以保证 SSR 兼容。
  • 使用 v5 柯里化语法。
  • 遵循 SOLID 路径组织 store。
  • 始终使用选择器模式 useStore((s) => s.field) 以提升性能。
  • 每个领域一个 store(auth、cart、ui、theme)。
  • 服务端数据使用 TanStack Query 处理。
  • devtools 仅在开发环境使用,用 process.env 检查包裹。
  • persist 使用 partialize 仅持久化必要字段,绝不持久化令牌。

禁止模式

  • App Router 中使用全局 store:会导致用户间请求共享,应改用基于 Context 的 store。
  • 在服务端组件中使用 Zustand:RSC 中没有 React hooks,应直接获取数据。
  • 持久化认证令牌:存在安全漏洞,应使用 httpOnly cookies。
  • 对对象不使用 useShallow:会导致过度重渲染,应使用 useShallow(selector)。
  • 使用 v4 语法:会破坏 TypeScript 推断,应使用 v5 柯里化 create<T>()()。

限制

该技能不覆盖服务端状态缓存,相关需求应参考 nextjs-tanstack-query。文档中未提供具体的安装命令、代码示例细节、收费或价格信息。