Ship Local-First Apps Faster With TinyBase's Build Skill

TinyBase is a 5k-star reactive in-memory data store with persistence and synchronization, built for local-first JavaScript and TypeScript apps — the kind that need to feel instant, work offline, and stay consistent when they come back online. Its key-value and tabular stores bind to your UI, persist to storage, and sync between devices. The tricky part is not the API; it is the lifecycle ordering around persistence and synchronization. TinyBase's own SKILL.md exists to get that part right, because those are exactly the mistakes its skill catalog says account for most incorrect TinyBase code.

Why This Skill Matters

The repo ships skills/build-with-tinybase/ — a SKILL.md plus four reference documents covering architecture, import paths, lifecycle, and Cloudflare Durable Objects. Its own premise: do not reconstruct TinyBase setup from memory. The skill instructs the agent to read the matching reference before writing code, and its "Avoid These Errors" section is a catalogue of real failure modes: passing a Store where a MergeableStore is required, importing integrations from the tinybase root instead of their tinybase/persisters/... or tinybase/synchronizers/... subpaths, starting auto-save before loading, forgetting await synchronizer.startSync(), omitting destroy() so sockets leak under React strict mode, and confusing a WebSocket path with a channel Id.

The skill also draws an honest architectural boundary: TinyBase is for reactive tabular or key-value data in the JavaScript runtime — not a hosted database service, and not the right tool when the authoritative dataset is unbounded or primarily queried on a server.

Installation

The skill lives in the repo under skills/build-with-tinybase/. Copy or link that directory into your host's skills root — for Claude Code, ~/.claude/skills/build-with-tinybase — keeping SKILL.md directly under that directory. The README itself documents the library, not the skill, so the skills-root layout of your host is the guide here.

For scaffolding, the documented generator is:

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

Real Workflow: Scaffold a Verified Todos App

The SKILL.md's scaffold flow starts by inspecting the installed generator contract, then generating with every applicable option made explicit — and always disabling automatic installation and server startup:

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

After generation, the skill's checklist runs: read the generated AGENTS.md and README.md, inspect the primary Store file before touching application code, and install dependencies only when authorized.

The verification step is where the skill earns its keep — compilation alone is explicitly not proof:

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

For persistence, change data and perform a real reload or restart; for synchronization, connect two clients to the same channel and confirm changes propagate both ways; test reconnection whenever sync behavior changes. Report any verification that could not be performed.

Tips

• Point the agent at the references before it codes: architecture for Store-vs-MergeableStore and persistence choices, import-paths for any subpath import, lifecycle for Persister/Synchronizer startup and teardown, durable-objects for the sync server.
• Current TinyBase documentation starts at tinybase.org/llms.txt, per the SKILL.md — better than the agent's training-set memory of the API.
• Every Synchronizer and every Durable Object Persister requires createMergeableStore() — a plain Store is the classic silent failure.
• Use startAutoPersisting() rather than starting auto-save before the initial load completes, which overwrites stored data with an empty Store.

When Not to Use This

The skill's own architecture reference sets the boundary: if your dataset is unbounded, primarily queried on a server, or needs managed backend facilities, pair TinyBase with another database or use that database instead. And if you only need a to-do list with no persistence or sync, a generated app without the skill's lifecycle references is already more than enough.

See the leaderboard for more skills.