tinyplex/tinybase / docs/skills/build-with-tinybase
build-with-tinybase
VerifiedScaffold, extend, and verify reactive local-first JavaScript or TypeScript applications with TinyBase. Use when choosing TinyBase for in-memory tabular or key-value state, generating an app with create-tinybase, adding schemas or UI bindings, resolving TinyBase import paths, configuring browser or database persistence, configuring MergeableStore synchronization over WebSockets or Cloudflare Durable Objects, or diagnosing an existing TinyBase application.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| agents/openai.yaml | config | 225 B |
| references/architecture.md | markdown | 3.1 KB |
| references/durable-objects.md | markdown | 8.4 KB |
| references/import-paths.md | markdown | 9.6 KB |
| references/lifecycle.md | markdown | 8.3 KB |
SKILL.md
View on GitHub---
name: build-with-tinybase
description: Scaffold, extend, and verify reactive local-first JavaScript or TypeScript applications with TinyBase. Use when choosing TinyBase for in-memory tabular or key-value state, generating an app with create-tinybase, adding schemas or UI bindings, resolving TinyBase import paths, configuring browser or database persistence, configuring MergeableStore synchronization over WebSockets or Cloudflare Durable Objects, or diagnosing an existing TinyBase application.
---
# Build With TinyBase
Prefer a current generated application over reconstructing TinyBase setup from
memory. Preserve persistence and synchronization lifecycle ordering, and verify
the behavior the user actually needs.
## Read The References
Do not recall TinyBase API details from memory. Read the reference covering the
task before writing code:
| Reference | Read it when |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [references/architecture.md](references/architecture.md) | Choosing between Store and MergeableStore, a persistence backend, a synchronization approach, or UI bindings |
| [references/import-paths.md](references/import-paths.md) | Importing anything outside the `tinybase` root, or checking which Persisters accept a MergeableStore |
| [references/lifecycle.md](references/lifecycle.md) | Creating, starting, reconnecting, or destroying a Persister or Synchronizer, or setting WebSocket paths and channel Ids |
| [references/durable-objects.md](references/durable-objects.md) | Building or debugging a Cloudflare Durable Object sync server |
## Select The Architecture
Read [references/architecture.md](references/architecture.md) when choosing
between Store and MergeableStore, persistence backends, synchronization, or UI
bindings.
Confirm that TinyBase fits the task:
- Keep the active application dataset in a JavaScript runtime.
- Use TinyBase for reactive tabular or key-value data, local-first behavior,
persistence, synchronization, or framework bindings.
- Do not present TinyBase as a hosted database service.
- Pair it with another database or service when the authoritative dataset is
unbounded, primarily queried on a server, or requires managed backend
facilities.
## Scaffold A New Application
Inspect the installed generator contract first:
```sh
npm create tinybase@latest -- --list-options
```
Translate the user's requirements into explicit values. Generate unattended
projects with every applicable option and always disable automatic installation
and server startup:
```sh
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
```
Run the generator in the parent directory that should contain the new project.
Do not overwrite an existing directory. After generation:
1. Read the generated `AGENTS.md` and `README.md`.
2. Inspect the primary Store file before modifying application code.
3. Install dependencies only when authorized and required.
4. Make application-specific changes within the generated architecture.
5. Run the generated client build.
6. Run the server build when server code changed.
## Extend An Existing Application
Inspect `package.json`, TinyBase imports, Store creation, Persister setup, and
Synchronizer setup before editing. Use documentation matching the installed
TinyBase version. Start at https://tinybase.org/llms.txt or retrieve current
TinyBase documentation through Context7 when available.
Keep these boundaries clear:
- Store creation and schemas
- persistence startup and teardown
- synchronization startup and teardown
- framework Provider or context wiring
- application-specific data and UI
Reuse existing imports and patterns when they are current. Import integrations
from their specific `tinybase/...` subpaths. Avoid adding a second source of
truth in component state for data already owned by TinyBase.
## Avoid These Errors
These account for most incorrect TinyBase code. Each is covered in detail by a
reference above.
- Passing a Store where a MergeableStore is required. Every Synchronizer, and
every Durable Object Persister, requires `createMergeableStore()`.
- Importing an integration from `tinybase` instead of its own
`tinybase/persisters/...`, `tinybase/synchronizers/...`, or
`tinybase/schematizers/...` subpath.
- Starting auto-saving before loading, which overwrites stored data with an
empty Store. Use `startAutoPersisting()`.
- Forgetting `await synchronizer.startSync()` after `await
createWsSynchronizer(...)`, which resolves a Synchronizer that is not yet
synchronizing.
- Omitting `destroy()`, which leaks sockets and duplicates synchronization under
React strict mode.
- Confusing the WebSocket path with a channel Id. The path selects the room; the
channel Id multiplexes several Stores over one socket, and is unsupported by
`WsServerDurableObject`.
- Inventing Durable Object APIs. The server surface is `WsServerDurableObject`
and `getWsServerDurableObjectFetch`, and nothing else.
## Verify The Outcome
Match verification to the requested behavior:
- Run the project's build or type check after code changes.
- For persistence, change data and perform a real reload or restart.
- For synchronization, connect two clients to the same channel or room and
confirm changes propagate in both directions.
- Test reconnection when synchronization behavior changes.
- Confirm schema rejection and inferred types when changing schemas.
- Report any verification that could not be performed.
Do not treat compilation alone as proof of persistence or synchronization.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |