mcpField
J
jotai

jotai

github.com/jotaijs开发5424 次安装2 周前更新
代码仓库

关于 jotai

jotai 是面向使用 Jotai 的开发者的编码技能，帮助基于版本和项目现状设计状态、实现变更并验证行为。内容强调原子与 store 的边界、最小改动，以及按任务查阅参考资料。

主要功能

  1. 01分析状态归属、store 与原子身份
  2. 02按需选择读取、写入与订阅方式
  3. 03指导异步状态和副作用处理
  4. 04提供性能、TypeScript 与测试参考
  5. 05核实 Jotai 及扩展包版本兼容性

适用场景

  1. 01为新代码选择 Jotai v3 状态模式
  2. 02排查组件订阅与 store 隔离问题
  3. 03为异步读取或副作用选择实现方式
  4. 04根据已安装版本处理 API 迁移

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jotaijs/jotai-skills --skill jotai

安装后在 Claude Code 中输入/jotai确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
async-and-side-effects.md
atom-modeling.md
extensions-decision-guide.md
performance-and-large-state.md
react-usage.md
recipes-decision-guide.md
tools-and-debugging.md
typescript-and-testing.md
utilities-decision-guide.md
version-migration.md

详细介绍

Jotai

概述

新代码以 Jotai v3 为基准。对于现有项目，提供与版本相关的建议前，先检查已安装的 Jotai 和扩展版本。保留用户要求的行为、架构和依赖选择；仅在有助于完成任务时提供重构建议。

工作流

  • 修改代码前，先确认状态的所有权、各读取方和写入方使用的 store、atom 的身份、异步行为以及相关测试。
  • 选择满足请求的最小改动。派生计算值；在有帮助时拆分独立更新的状态；如果命令适合通过共享更新路径处理，则使用命名 action atom。
  • 在适当的层级验证行为：用 vanilla store 测试状态逻辑和隔离性，用组件测试订阅和用户交互。实际可行时，沿用现有测试设置。

核心不变量

  • Atom 配置通过引用标识状态；值属于 store。确保 atom 配置在多次渲染间保持稳定，并让状态流中的所有参与方使用同一个 store。
  • 以不可变方式替换对象和数组值。Jotai 使用 Object.is 检测值变化；修改值后再设置同一个引用可能会抑制更新。
  • 读取函数中的 get 会追踪依赖；写入函数中的 get 只读取值，不会建立响应式订阅。避免在读取中执行无关副作用。
  • 读取时使用 useAtomValue，写入时使用 useSetAtom，两者兼用时使用 useAtom。在命令式集成中使用 vanilla get/set/sub；仅仅读取不会挂载 atom。
  • 明确初始化和订阅的生命周期。onMount 由 atom 订阅触发，而非模块加载或 setter 调用。在服务端隔离由请求拥有的状态。
  • 优先使用普通 atom 组合，再考虑工具。仅当工具或扩展能更清晰地表达所需语义时才添加，并检查其是否兼容已安装的主版本。

参考资料路由

仅阅读与任务匹配的文件：

  • references/atom-modeling.md：用于确定 atom 的边界、派生 atom、action atom、可写适配器、重置、存储以及类似 family 的参数化 atom。
  • references/react-usage.md：用于选择 hook、确定 Provider/store 作用域、vanilla 集成、SSR、hydration、动态创建 atom 以及组件架构。
  • references/async-and-side-effects.md：用于处理 Suspense、异步读取、异步 action、中止信号、非 Suspense 状态、刷新流程和外部副作用。
  • references/performance-and-large-state.md：用于渲染调优、selectAtom、focusAtom、splitAtom、大型对象、列表以及依赖图深度。
  • references/typescript-and-testing.md：用于 TypeScript 类型推断、可写 atom 参数类型、ExtractAtomValue 以及测试策略。
  • references/utilities-decision-guide.md：用于选择内置工具，例如存储、SSR hydration、可重置/默认 atom、惰性 atom、回调、reducer、select、split 以及 family 迁移。
  • references/extensions-decision-guide.md：用于选择扩展包，例如 TanStack Query、optics、Immer、effects、location、scope、cache、XState、GraphQL/RPC 以及外部存储桥接。
  • references/tools-and-debugging.md：用于选择 Devtools、Babel、SWC 和 Rolldown 支持，以实现调试、标签、React Refresh 和打包工具集成。
  • references/recipes-decision-guide.md：用于判断何时使用或调整官方示例，例如 debounce、listeners、broadcast、compare、toggle、自定义 hook、reducer hook 和 atom effects。
  • references/version-migration.md：用于从 v2 迁移到 v3，包括提高后的 React/TypeScript/Node 要求、仅 ESM 的打包方式、已移除 API 及其替代方案，以及 jotai/vanilla/internals 的变更。

兼容性与源码验证

此修订以 Jotai 3.0.1 为依据，并涵盖 Jotai 2.20.x 中两者存在差异的部分。在提供与版本相关的 API 指引前，请先确定目标项目安装的 Jotai 和扩展包版本，然后检查其导出的类型、源码或对应版本的文档和测试。不要假设当前文档与已安装版本一致。

评论

支持 Markdown