Client-side DO

@repo/client-side-do connects browser state to Cloudflare Durable Objects over WebSockets. It derives a client RPC surface from a Durable Object type, queues calls while connecting, reconnects automatically, and broadcasts successful method results to subscribers.

Typesafe RPC

Method names, arguments, results, and event payloads derive from the server target.

Realtime

Per-method and wildcard subscriptions receive server mutation events.

Resilient connection

Queued requests, reconnects, retries, and re-subscription are managed by the client.

Optimistic state

Helpers connect outbound mutations and inbound events to TanStack DB collections.

Architecture

graph LR
  UI[UI] --> DB[TanStack DB]
  DB --> C[Client-side DO]
  C -->|WebSocket RPC| DO[Durable Object]
  DO -->|response| C
  DO -->|events| O[Other clients]
  C --> DB
  O --> ODB[Local collections]

The Durable Object remains authoritative. Local collections provide immediate UI state and reconcile through method events.

Package boundaries

Use the browser-safe entrypoint from frontend code:

import {
  createDOTransport,
  createOptimisticActionMetadata,
} from '@repo/client-side-do/client';

Server code can import createRpcServer and shared RPC types from the package root:

import {
  createRpcServer,
  type RpcFromTarget,
} from '@repo/client-side-do';

Active development

The package is experimental and its high-level collection API is still being refined. Prefer the helper layer for new integrations, but pin revisions for production use.

Start here

1. Build the RPC server.
2. Connect a client and subscriptions.
3. Synchronize a TanStack DB collection.
4. Review the end-to-end mental model.