tinyplex/tinybase / skills/build-with-tinybase
build-with-tinybase
UnverifiedScaffold, 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 |
references/durable-objects.md
View on GitHub# TinyBase On Cloudflare Durable Objects
A Durable Object is the recommended production WebSocket server for TinyBase
synchronization. One Durable Object instance per URL path holds the connected
clients and, optionally, a durable server-side copy of the data.
Do not invent Durable Object APIs. The entire server surface is the
`WsServerDurableObject` class and the `getWsServerDurableObjectFetch` function,
both from `tinybase/synchronizers/synchronizer-ws-server-durable-object`.
The fastest correct start is to generate the whole stack and then edit it:
```sh
npm create tinybase@latest -- \
--non-interactive \
--projectName my-app \
--appType todos \
--language typescript \
--framework react \
--syncType durable-objects \
--persistenceType none \
--installAndRun false
```
## The Server
```ts
import {createMergeableStore, type IdAddedOrRemoved} from 'tinybase';
import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
import {
getWsServerDurableObjectFetch,
WsServerDurableObject,
} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';
export class TinyBaseDurableObject extends WsServerDurableObject {
createPersister() {
const store = createMergeableStore();
return createDurableObjectSqlStoragePersister(store, this.ctx.storage.sql);
}
onClientId(
pathId: string,
clientId: string,
addedOrRemoved: IdAddedOrRemoved,
) {
console.log(
`Client ${clientId} ${addedOrRemoved == 1 ? 'joined' : 'left'} /${pathId}`,
);
}
}
export default {fetch: getWsServerDurableObjectFetch('TinyBaseDurableObjects')};
```
Three things must line up, and they are the usual source of a broken deploy:
1. The class is exported from the worker entry point.
2. Its name matches `class_name` in the Wrangler configuration.
3. The string passed to `getWsServerDurableObjectFetch` is the binding **name**,
not the class name.
## Wrangler Configuration
```toml
name = "my-app-server"
main = "index.ts"
compatibility_date = "2024-10-11"
[[durable_objects.bindings]]
name = "TinyBaseDurableObjects"
class_name = "TinyBaseDurableObject"
[[migrations]]
tag = "v1"
new_sqlite_classes = ["TinyBaseDurableObject"]
```
Use `new_sqlite_classes` when the Durable Object uses SQLite storage, which it
does when `createPersister` returns a `DurableObjectSqlStoragePersister`. Use
`new_classes` for key-value storage only. A missing `[[migrations]]` block is
why a first deploy fails.
Install `wrangler` and `@cloudflare/workers-types` as dev dependencies, and
`tinybase` as a dependency, in the server package. Run `wrangler dev` locally
and `wrangler deploy` to ship.
## Server Persistence
`createPersister()` is optional. Without it the Durable Object relays messages
between clients but keeps nothing, so data survives only as long as at least one
client holds it.
Implement it to keep a durable server copy. The method may be synchronous or
asynchronous, and must return a `Persister<Persists.MergeableStoreOnly>` over a
MergeableStore. Two Persisters fit:
| Import | Create | Storage |
| ---------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------ |
| `tinybase/persisters/persister-durable-object-sql-storage` | `createDurableObjectSqlStoragePersister(store, this.ctx.storage.sql)` | Durable Object SQLite |
| `tinybase/persisters/persister-durable-object-storage` | `createDurableObjectStoragePersister(store, this.ctx.storage)` | Durable Object key-value |
Prefer the SQLite variant for anything beyond trivial data. Do not call
`load()`, `startAutoPersisting()`, or `destroy()` on it yourself — return the
Persister and `WsServerDurableObject` manages its lifecycle.
Neither Persister accepts a plain Store. Always `createMergeableStore()`.
## The Client
```ts
import {createMergeableStore} from 'tinybase';
import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';
import ReconnectingWebSocket from 'reconnecting-websocket';
const store = createMergeableStore();
const synchronizer = await createWsSynchronizer(
store,
new ReconnectingWebSocket('wss://my-app-server.workers.dev/' + roomId),
);
await synchronizer.startSync();
synchronizer.getWebSocket().addEventListener('open', () => {
synchronizer.load().then(() => synchronizer.save());
});
```
See [lifecycle.md](lifecycle.md) for why the `open` handler matters and how to
wire this in React or Solid.
## Paths
The URL path is the room. Every client connecting to `/roomA` reaches one
Durable Object instance; `/roomB` reaches a different one. They share nothing.
Shared WebSockets and channel Ids — the optional third argument to
`createWsSynchronizer` — are **not** supported by `WsServerDurableObject`,
because each path is a separate instance. Use `WsServer` or `WsServerSimple` if
several Stores must multiplex over one socket.
## Overridable Methods
Override only what is needed. Every method has a working default.
| Method | Purpose |
| ------------------------------------------------------------- | -------------------------------------------------------- |
| `createPersister()` | Return a server-side Persister, or nothing |
| `getPathId()` | The path this instance serves |
| `getClientIds()` | Currently connected client Ids |
| `getFragmentSize()` | Message fragment size, or `undefined` for no fragmenting |
| `getRequestTimeoutSeconds()` | Synchronization request timeout |
| `onPathId(pathId, addedOrRemoved)` | A path started or stopped being served |
| `onClientId(pathId, clientId, addedOrRemoved)` | A client joined or left |
| `onMessage(fromClientId, toClientId, remainder)` | Observe relayed messages |
| `onIgnoredError(error)` | Observe errors that are otherwise swallowed |
| `authorize(pathId, request)` | Accept or refuse a client, and how it may write |
| `canWriteCell(pathId, tableId, rowId, cellId, cell, context)` | Whether a client may write a Cell |
| `canWriteValue(pathId, valueId, value, context)` | Whether a client may write a Value |
`addedOrRemoved` is `1` for added and `-1` for removed.
## Authentication
`getWsServerDurableObjectFetch` performs no authentication. It requires a
WebSocket `Upgrade` request carrying a `sec-websocket-key` header, and routes on
the request path alone.
Since v10.1, the Durable Object itself can authorize clients. Override
`authorize(pathId, request)` to return a `ClientAccess` object - `{readOnly?,
context?}` - or `undefined`, which refuses the upgrade with a `403`. Override
`canWriteCell(pathId, tableId, rowId, cellId, cell, context)` and
`canWriteValue(pathId, valueId, value, context)` to decide what a writable
client may change. The `ClientAccess` object is kept with the WebSocket, so it
survives hibernation; keep it within Cloudflare's 2,048-byte attachment limit.
Overriding any of these makes `fetch` asynchronous, so await `super.fetch()` if
you override that too, and override `createPersister` as well, since otherwise
the Durable Object keeps an in-memory MergeableStore that eviction discards.
To scope a client to a verified user or tenant by path, write the worker's
`fetch` handler directly: validate the request, then forward a request of your
own to the Durable Object stub, rewriting the path rather than trusting one the
client chose.
Client Ids are derived from the `Sec-WebSocket-Key` header. They change across
reconnections and are not identities. Do not authorize on them.
## Verifying
Run `wrangler dev`, open two clients on the same path, and confirm changes
propagate both ways. Then reload one client and confirm the data is still there,
which is what proves `createPersister` is working rather than just the relay.
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: 117k | Updated | Claude CodeCodex | Unverified | 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: 117k | Updated | Claude CodeCodex | Unverified | Install |