Sync

Smithers custom UIs use TanStack DB as the frontend data layer: UI code reads collections via useLiveQuery, writes through the domain API, and the provider changes with workspace mode.

import { QueryClient } from "@tanstack/react-query";
import { useLiveQuery } from "@tanstack/react-db";
import { createSmithersCollections } from "smthrs/gateway-client";

const queryClient = new QueryClient();
const collections = createSmithersCollections(
  { kind: "local", apiBaseUrl: "http://127.0.0.1:7331" },
  queryClient,
);

const { data: runs } = useLiveQuery((q) =>
  q.from({ run: collections.runs({ limit: 50 }) }),
);

WorkspaceMode

WorkspaceMode selects the provider:

type WorkspaceMode =
  | { kind: "local"; apiBaseUrl: string; token?: string }
  | {
      kind: "multiplayer";
      apiBaseUrl: string;
      electricBaseUrl: string;
      workspaceId: string;
      token?: string;
    };

SmithersGatewayProvider defaults to local mode from the Gateway client base URL; pass mode to createGatewayReactRoot or SmithersGatewayProvider for multiplayer.

Collections

createSmithersCollections(mode, queryClient) returns the same collection names in every mode:

collections.runs()
collections.run(runId)
collections.runTree(runId)
collections.nodes(runId)
collections.runEvents(runId)
collections.approvals()
collections.workflows()
collections.docs()
collections.prompts()
collections.scores({ runId })
collections.tickets()
collections.memoryFacts()
collections.crons()

Large node blobs stay fetch-on-demand via useGatewayNodeOutput and useGatewayRpc("getNodeDiff", ...), not collection rows.

Local Provider

Local workspaces use the official QueryCollection provider over the Gateway REST domain API:

GET  /v1/api/runs
GET  /v1/api/runs/:id
POST /v1/api/runs
GET  /v1/api/events?runId=...
GET  /v1/api/approvals
GET  /v1/api/stream

GET /v1/api/stream is an SSE invalidation feed; change frames look like this:

event: change
data: {"seq":42,"collections":["runs","events"]}

The client invalidates matching TanStack Query keys and QueryCollection refetches from /v1/api/*; the stream coalesces bursts, sends heartbeats, reconnects with backoff, and bounds its buffers, sending a reset event (which invalidates every collection key) when the ring can’t replay a missed sequence. SQLite and embedded PGlite mutating routes return { seq }, the invalidation sequence that confirms the local optimistic write.

Multiplayer Provider

Multiplayer workspaces use the official ElectricCollection provider through @smthrs/electric-proxy:

ElectricCollection -> electricBaseUrl/v1/shape -> electric-proxy -> Postgres

The proxy owns shape scoping, auth, and rate limits; the client passes the catalog shape name and its domain-API auth token. Electric rows map snake_case Postgres columns to the same camelCase types REST returns, so React components and useLiveQuery code never branch on mode. Writes still go through /v1/api/*: Postgres mutating routes return { txid }, captured inside the write transaction with pg_current_xact_id()::xid::text, which Electric transaction matching uses to confirm optimistic state once the shape stream catches up.

React Hooks

The workflow UI hook surface is preserved on top of collections:

useGatewayRun(runId)
useGatewayRunEvents(runId)
useGatewayRunTree(runId)
useGatewayApprovals({ filter: { runId } })
useGatewayNodeOutput({ runId, nodeId })
useGatewayActions()
useGatewayConnectionStatus()

Use these hooks for workflow UIs, and useSmithersCollections() for a custom collection query:

import { useLiveQuery } from "@tanstack/react-db";
import { useSmithersCollections } from "smthrs/gateway-react";

function ScoreList({ runId }: { runId: string }) {
  const { collections } = useSmithersCollections();
  const scores = useLiveQuery(
    (q) => q.from({ score: collections.scores({ runId }) }),
    [collections, runId],
  );

  return <pre>{JSON.stringify(scores.data ?? [], null, 2)}</pre>;
}

Domain Writes

Collection mutation handlers call the same domain API that useGatewayActions() calls:

await collections.runs().insert({
  runId: crypto.randomUUID(),
  workflowKey: "deploy",
  workflow: "deploy",
  status: "queued",
  input: { env: "prod" },
});

Confirmation follows the paths above: SSE invalidation for local mode, Electric transaction matching on txid for multiplayer. Shape streams are read-only.

Start

Articles

Learn

Capabilities

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

WorkspaceMode

Collections

Local Provider

Multiplayer Provider

React Hooks

Domain Writes

​WorkspaceMode

​Collections

​Local Provider

​Multiplayer Provider

​React Hooks

​Domain Writes

WorkspaceMode

Collections

Local Provider

Multiplayer Provider

React Hooks

Domain Writes