React SDK

@pylonsync/react is the React client. The db.* namespace exposes hooks that read from a local sync replica. Every component using a hook re-renders automatically when a row changes (your own mutation, a server push, a write from another tab).

Install

bun add @pylonsync/react
# or: npm i @pylonsync/react

Initialize once

Pick any entry point that runs before your first hook (src/main.tsx, a Next.js root client provider, a top-level component effect):

import { init } from "@pylonsync/react";

init({ baseUrl: "http://localhost:4321" });

In Next.js + Vercel, omit baseUrl (or pass "") so the client talks same-origin and the Next rewrite forwards /api/* to your Pylon backend.

The `db.*` namespace

db is the public API for apps using a single global sync engine. Every method below subscribes to or writes to the same shared replica.

`db.useQuery` — live list

import { db } from "@pylonsync/react";

type Todo = { id: string; title: string; done: boolean };

export function TodoList() {
  const { data: todos, loading, error } = db.useQuery<Todo>("Todo");
  if (loading) return <Spinner />;
  if (error) return <ErrorBanner error={error} />;
  return <ul>{todos.map((t) => <li key={t.id}>{t.title}</li>)}</ul>;
}

loading is true only while there is nothing to show and the first server pull has not landed. With a warm local cache it is false at once, even before this session has talked to the server. synced is true once the engine has completed a pull in this session (it goes back to false after an org or account switch until the re-pull lands, and stays false while offline). Check it where a partial list would mislead: counts, “no results”, billing state.

const { data: invoices, synced } = db.useQuery<Invoice>("Invoice");
return synced && invoices.length === 0 ? <EmptyState /> : <InvoiceTable rows={invoices} />;

With filtering / ordering / limits:

const { data } = db.useQuery<Todo>("Todo", {
  where: { authorId: "u_xyz", done: false },
  orderBy: { createdAt: "desc" },
  limit: 50,
});

where takes a value (equality) or operators: $gt, $gte, $lt, $lte, $not, $in, $like. The query runs on the local replica and gives the same rows as the server:

Numbers compare as numbers.
Strings compare by character code, so "B" comes before "a".
Two RFC 3339 timestamps compare as times, whatever their offset or precision. occurredAt: { $gte: "2026-10-01T00:00:00Z" } matches 2026-10-01T00:00:00.000Z.
A row with no value for the field matches no range.

An operator that cannot apply, such as a number against a string or an unknown operator, matches no rows and logs a warning in development.

`db.useQueryOne` — single row by ID

const { data: post, loading, synced } = db.useQueryOne<Post>("Post", postId);

A null row with synced: false may still exist on the server.

`db.useInfiniteQuery` — paginated with `loadMore`

const { data, hasMore, loadMore, loading } = db.useInfiniteQuery<Post>("Post", {
  pageSize: 20,
});

`db.useReactiveQuery` — server-side query, auto re-runs

For Convex-style server functions that the framework re-runs whenever their dependency set changes:

const { data: feed, loading } = db.useReactiveQuery<FeedItem[]>("getFeed", {
  userId: currentUser.id,
});

The server records every ctx.db.* read inside your query() handler and re-runs the handler when any of those rows mutate. See Reactive queries.

`db.useMutation` — server function with optimistic updates

const send = db.useMutation<
  { channelId: string; body: string },
  { messageId: string }
>("sendMessage", {
  optimistic: (args, ctx) => ({
    entity: "Message",
    data: {
      id: ctx.id,
      channelId: args.channelId,
      body: args.body,
      authorId: me.id,
      createdAt: ctx.now,
    },
  }),
});

await send.mutate({ channelId, body: "Hi!" });

The ghost row appears in db.useQuery("Message", ...) instantly; the server’s broadcast reconciles in-place. See Optimistic updates.

`db.useEntity` — optimistic CRUD bound to one entity

When you’d rather call insert/update/delete directly than wire a server function:

const { insert, update, remove } = db.useEntity("Todo");

await insert({ title: "Buy milk", done: false });
await update(todoId, { done: true });
await remove(todoId);

Same store + reconciliation as db.useMutation. The change is in the local store before the promise settles. The promise resolves when the server applies the write, or when the server can’t be reached and the write is queued for retry. It rejects with a MutationRejectedError when the server refuses the write (policy denial, validation); the optimistic change is rolled back first.

import { MutationRejectedError } from "@pylonsync/react";

try {
  await insert({ channelId, body });
} catch (err) {
  if (err instanceof MutationRejectedError) showToast(`Not sent: ${err.message}`); // err.code, e.g. "POLICY_DENIED"
  else throw err;
}

`useOutbox` — unsynced and failed writes

useOutbox() lists the writes on this device that are not on the server. It re-renders when a write is queued, applied, rejected, retried, or dismissed.

import { useOutbox } from "@pylonsync/react";

function SyncStatus() {
  const { pending, failed, retry, dismiss } = useOutbox();
  return (
    <div>
      {pending.length > 0 && <p>{pending.length} not synced</p>}
      {failed.map((w) => (
        <div key={w.id}>
          <p>{w.entity} not saved: {w.error}</p>
          <button onClick={() => retry(w.id)}>Retry</button>
          <button onClick={() => dismiss(w.id)}>Dismiss</button>
        </div>
      ))}
    </div>
  );
}

pending: writes made offline, or waiting for a sign-in. Oldest first.
failed: writes the server rejected, with error and errorCode.
retry(id, data?): applies the write again and sends it, with data merged over its fields. It rejects with a MutationRejectedError when the server rejects it again, or when another user is signed in.
dismiss(id): drops a failed write.

`queueUpload` and `useFileUrl` — photos taken offline

queueUpload(file, { attach }) keeps a file on the device and uploads it when there is a network, then sets it on its record. useFileUrl(value) shows a local: value from the copy on the device. See Offline apps.

`useAppUpdate` — a new deploy is available

In an app with buildManifest({ offline }), useAppUpdate() reports when a newer build is deployed. apply() waits until the outbox has no pending writes, then loads the new build. <AppUpdateBar /> is a minimal notice that uses it. See Offline apps.

const { updateReady, applying, apply } = useAppUpdate();

`db.useSearch` — live faceted search

const { hits, facetCounts, total } = db.useSearch<Product>("Product", {
  query: "red sneakers",
  filters: { category: "shoes" },
  facets: ["brand", "color"],
  sort: ["price", "desc"],
});

Requires the search plugin enabled per-entity in your schema. See Search.

`db.useAggregate` — live count / sum / avg / groupBy

const { data: stats } = db.useAggregate("Order", {
  count: "*",
  sum: ["amount"],
  groupBy: ["status"],
  where: { customerId: "c_xyz" },
});

count is "*" (or a column name for COUNT(col)); sum / avg / min / max take arrays of column names; groupBy takes an array of columns (or date-bucket specs). data is one row per group.

Sessions

import { useSession } from "@pylonsync/react";
import { db } from "@pylonsync/react";

function NavBar() {
  const { auth, signOut } = useSession(db.sync);
  if (!auth) return <a href="/login">Sign in</a>;
  return (
    <>
      <span>{auth.user.displayName}</span>
      <button onClick={signOut}>Sign out</button>
    </>
  );
}

useSession returns a live auth object that re-renders on sign-in, sign-out, org switch, or remote session revoke. It also exposes selectOrg, clearOrg, and refresh for multi-tenant flows.

Connection status

import { useSyncStatus } from "@pylonsync/react";

function ConnectionIndicator() {
  const status = useSyncStatus();
  // "connected" | "connecting" | "reconnecting" | "offline"
  if (status === "connected") return null;
  return <div className="banner">{status}…</div>;
}

Presence + rooms

import { useRoom } from "@pylonsync/react";

function Editor({ docId, userId }: { docId: string; userId: string }) {
  const room = useRoom(`doc:${docId}`, userId);
  return (
    <>
      {room.peers.map((p) => (
        <Cursor key={p.id} x={p.presence.x} y={p.presence.y} />
      ))}
      <textarea
        onChange={(e) => room.setPresence({ cursor: e.target.selectionStart })}
      />
    </>
  );
}

Rooms tied to a row

A free room name (chat-42, doc:${docId}) is open to any signed-in user who knows it. For a row’s presence, pass the row instead:

const room = useRoom({ entity: "Document", id: docId }, userId);
if (room.denied) return <p>You do not have access to this document.</p>;

The room is named @Document/<id> (rowRoom(entity, id) builds the name), and the server runs the row’s read policy on every room operation: join, presence, heartbeat, messages, the member list, the room list and the WebSocket subscription. A missing row and a row the caller may not read get the same answer, ROOM_FORBIDDEN. A name that starts with @ and does not name a row is refused (INVALID_ROOM), so @ cannot start a free room. Someone who loses access while in the room (the document is unshared) stops receiving its events within 5 seconds of the change. Within 10 seconds the server removes them from the room, even when nobody in it acts: the others get their leave, and their own hook sets denied, clears peers, and stops rejoining. A member on the HTTP polling fallback (no WebSocket) is removed at their next heartbeat. On a deployment with more than one machine, room membership is kept per machine. When someone connected through two machines closes the connection on one, people on the other machines can stop seeing them until their next presence update.

Joining and staying in a room

The hook joins over HTTP first and subscribes over the WebSocket after the join lands. While joined it sends POST /api/rooms/heartbeat every 45 s; the server drops a member after 120 s without activity and tells the room. When the server reports the member gone (a heartbeat returns alive: false, or a resubscribe after a reconnect gets NOT_IN_ROOM), the hook rejoins and resubscribes. A closed socket removes the user only from rooms no other socket of that user still holds.

Multiplayer shards

For tick-driven multiplayer (games, collaborative canvases):

import { useShard } from "@pylonsync/react";

const { snapshot, send, connected } = useShard<GameState, Input>(
  `match_${matchId}`,
  { subscriberId: userId },
);

When the server moves the player to another shard (ctx.shards.transfer), the hook reconnects there on its own; its shardId field is the shard it is connected to. When a deploy moves the shard itself to another machine, the hook reconnects the same way and its shardId stays. See Move a player to another shard and Deploys. See Live queries → shards.

Imperative calls

For one-shot reads/writes outside the React tree (effects, event handlers, server-rendered code):

import { db } from "@pylonsync/react";

const id = await db.insert("Todo", { title: "x", done: false });
await db.update("Todo", id, { done: true });
await db.delete("Todo", id);

const result = await db.fn<{ ok: boolean }>("processOrder", { orderId });

for await (const chunk of db.streamFn("chat", { prompt: "hi" })) {
  console.log(chunk);
}

These hit the local store optimistically (where applicable) and the server in the background. They use the same path as the hooks.

Auth helpers

For sign-in flows that the framework owns end-to-end (cookie + storage update + session refresh), use the @pylonsync/next/auth helpers (works outside Next.js too; the auth module has no Next-specific deps despite the package path):

import {
  loginWithPassword,
  signupWithPassword,
  logout,
  startOAuthLogin,
} from "@pylonsync/next/auth";

await loginWithPassword({ email, password });
await logout();

For long-running clients, run the session auto-refresher to keep tokens fresh:

import { startSessionAutoRefresh } from "@pylonsync/react";

const cancel = startSessionAutoRefresh({ intervalSeconds: 300 });
// later: cancel()

TypeScript

For end-to-end type safety from schema → hooks, use createTypedDb with your manifest’s generated types:

import { createTypedDb } from "@pylonsync/react";
import type { Schema } from "./pylon.codegen";

export const typedDb = createTypedDb<Schema>();

// Now `typedDb.useQuery("Todo")` autocompletes the entity name +
// types `data` as `Todo[]` automatically.

Run pylon codegen client --target ts to emit Schema from your app.ts.

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

Install

Initialize once

The `db.*` namespace

`db.useQuery` — live list

`db.useQueryOne` — single row by ID

`db.useInfiniteQuery` — paginated with `loadMore`

`db.useReactiveQuery` — server-side query, auto re-runs

`db.useMutation` — server function with optimistic updates

`db.useEntity` — optimistic CRUD bound to one entity

`useOutbox` — unsynced and failed writes

`queueUpload` and `useFileUrl` — photos taken offline

`useAppUpdate` — a new deploy is available

`db.useSearch` — live faceted search

`db.useAggregate` — live count / sum / avg / groupBy

Sessions

Connection status

Presence + rooms

Rooms tied to a row

Joining and staying in a room

Multiplayer shards

Imperative calls

Auth helpers

TypeScript

​Install

​Initialize once

​The db.* namespace

​db.useQuery — live list

​db.useQueryOne — single row by ID

​db.useInfiniteQuery — paginated with loadMore

​db.useReactiveQuery — server-side query, auto re-runs

​db.useMutation — server function with optimistic updates

​db.useEntity — optimistic CRUD bound to one entity

​useOutbox — unsynced and failed writes

​queueUpload and useFileUrl — photos taken offline

​useAppUpdate — a new deploy is available

​db.useSearch — live faceted search

​db.useAggregate — live count / sum / avg / groupBy

​Sessions

​Connection status

​Presence + rooms

​Rooms tied to a row

​Joining and staying in a room

​Multiplayer shards

​Imperative calls

​Auth helpers

​TypeScript

Install

Initialize once

The `db.*` namespace

`db.useQuery` — live list

`db.useQueryOne` — single row by ID

`db.useInfiniteQuery` — paginated with `loadMore`

`db.useReactiveQuery` — server-side query, auto re-runs

`db.useMutation` — server function with optimistic updates

`db.useEntity` — optimistic CRUD bound to one entity

`useOutbox` — unsynced and failed writes

`queueUpload` and `useFileUrl` — photos taken offline

`useAppUpdate` — a new deploy is available

`db.useSearch` — live faceted search

`db.useAggregate` — live count / sum / avg / groupBy

Sessions

Connection status

Presence + rooms

Rooms tied to a row

Joining and staying in a room

Multiplayer shards

Imperative calls

Auth helpers

TypeScript