---
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.