Skip to content

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

build-with-tinybase

Unverified

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

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.
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: 117kUpdated Claude CodeCodexUnverifiedInstall
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: 117kUpdated Claude CodeCodexUnverifiedInstall