用 TinyBase 的构建 Skill 更快交付本地优先应用

TinyBase 是一个 5k 星的响应式内存数据存储，自带持久化与同步，专为本地优先的 JavaScript 和 TypeScript 应用而建——也就是那些需要即时感受、离线可用、回来在线时保持一致的应用。它的键值和表格 store 可以绑定到你的 UI、落盘存储、在设备间同步。难的部分不是 API，而是持久化与同步周边的生命周期顺序。TinyBase 自带的 SKILL.md 就是为了把这部分做对，因为它的 skill 目录明确说这些正是大多数 TinyBase 代码错误的来源。

为什么这个 Skill 重要

仓库在 skills/build-with-tinybase/ 下附带了一份 SKILL.md 和四份参考文档，覆盖架构、导入路径、生命周期和 Cloudflare Durable Objects。它的前提是：不要凭记忆重建 TinyBase 的配置。skill 指示 Agent 在写代码之前先读对应的参考文档，而它的"Avoid These Errors"章节是一份真实失败模式的清单：把 Store 传给需要 MergeableStore 的地方、从 tinybase 根包而不是 tinybase/persisters/... 或 tinybase/synchronizers/... 子路径导入集成、在加载完成前启动自动保存、忘记 await synchronizer.startSync()、漏掉 destroy() 导致 React 严格模式下 socket 泄漏，以及把 WebSocket 路径和 channel Id 混为一谈。

skill 还划出了一条诚实的架构边界：TinyBase 用于 JavaScript 运行时内的响应式表格或键值数据——不是托管数据库服务，当权威数据集无界或主要在服务端查询时也不是合适的工具。

安装

skill 位于仓库的 skills/build-with-tinybase/。把这个目录复制或链接到你宿主的 skills 根目录——Claude Code 是 ~/.claude/skills/build-with-tinybase——并保持 SKILL.md 直接位于该目录之下。README 本身记载的是库的用法而不是这个 skill，所以这里以你宿主的 skills 目录布局为准。

脚手架方面，文档记载的生成器是：

npm create tinybase@latest -- --list-options

实战：脚手架一个经过验证的 Todos 应用

SKILL.md 的脚手架流程先检查已安装生成器的契约，然后把每个适用选项都显式写出再进行生成——并且总是关闭自动安装和服务启动：

npm create tinybase@latest -- \
  --non-interactive \
  --projectName my-tinybase-app \
  --appType todos \
  --language typescript \
  --framework react \
  --tinyWidgets false \
  --schemas true \
  --syncType none \
  --persistenceType local-storage \
  --prettier true \
  --eslint true \
  --installAndRun false

生成之后运行 skill 的清单：读生成的 AGENTS.md 和 README.md，在动应用代码之前先检查主 Store 文件，且只在获得授权时安装依赖。

验证环节是这个 skill 真正的价值所在——它明确表示编译通过不算是证明：

按 skill 的验证清单来：本地存储持久化要真的刷新页面确认数据还在，然后再跑一次构建和类型检查。

持久化要改动数据并真正刷新或重启；同步要把两个客户端连到同一个 channel 并确认变化双向传播；同步行为有变化时测试重连。无法执行的验证也要如实报告。

技巧

• 让 Agent 写代码前先读参考文档：架构文档管 Store 还是 MergeableStore 和持久化选型，导入路径文档管任何子路径导入，生命周期文档管 Persister/Synchronizer 的启动与销毁，durable-objects 文档管同步服务器。
• 按 SKILL.md 的指引，TinyBase 当前文档从 tinybase.org/llms.txt 开始——比 Agent 训练集里对 API 的记忆更可靠。
• 每个 Synchronizer 和每个 Durable Object Persister 都要求 createMergeableStore()——传普通 Store 是最典型的静默失败。
• 用 startAutoPersisting()，而不是在初始加载完成前启动自动保存——那会用空 Store 覆盖已存储的数据。

何时不用这个 Skill

skill 自己的架构参考设定了边界：如果你的数据集无界、主要在服务端查询、或需要托管后端设施，就把 TinyBase 和另一个数据库搭配使用，或者直接用那个数据库。如果你只需要一个没有持久化和同步的待办清单，不带 skill 的生命周期参考、直接用生成的应用就已经绰绰有余。

查看 排行榜 了解更多 skill。