build-with-tinybase ยท diff
git:20260711.cb02ff7 to git:20260919.15433fd
36 added, 1 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
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, configuring browser or database persistence, configuring MergeableStore synchronization, or diagnosing an existing TinyBase application.
+ 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.