/build-with-tinybase

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:

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:

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 beha