Skip to content

tinyplex/tinybase / docs/skills/build-with-tinybase

build-with-tinybase

Verified

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.

FileKindSize
SKILL.mdskill md6.1 KB
agents/openai.yamlconfig225 B
references/architecture.mdmarkdown3.1 KB
references/durable-objects.mdmarkdown8.4 KB
references/import-paths.mdmarkdown9.6 KB
references/lifecycle.mdmarkdown8.3 KB
---
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.
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall