> This page location: Realtime > Examples > TanStack
> Full Neon documentation index: https://neon.com/docs/llms.txt
>
> Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md

> Summary: Build a per-user todo app with TanStack Start, TanStack DB, Drizzle and Managed Better Auth on Neon Realtime: seal live queries in server functions, seed a Realtime collection in a route loader, and settle optimistic writes by txid.

# TanStack example

Full-stack example app using Realtime with TanStack.

Last updated: 2026-11-18

This example shows how to use Neon Realtime with [TanStack Start](https://tanstack.com/start), [TanStack DB](https://tanstack.com/db), Drizzle and Neon's [Managed Better Auth](https://neon.com/docs/auth/overview), with support for [auth](https://neon.com/docs/realtime/examples/tanstack#authorize-with-the-session), [SSR](https://neon.com/docs/realtime/examples/tanstack#server-side-rendering), [client-side reactivity](https://neon.com/docs/realtime/examples/tanstack#client-side-reactivity) and [optimistic mutations](https://neon.com/docs/realtime/examples/tanstack#optimistic-mutations).

The sections follow the same order as the guides, from [defining](https://neon.com/docs/realtime/examples/tanstack#defining-queries) and [sealing](https://neon.com/docs/realtime/examples/tanstack#sealing-queries) queries to writing to them, and show the TanStack code for each step.

**Tip: Full example on GitHub**

The complete app is in the [`realtime/with-tanstack`](https://github.com/neondatabase/examples/tree/main/realtime/with-tanstack) folder of the `neondatabase/examples` repository.

## Setup

Install the Realtime SDK with its Drizzle and TanStack DB bindings, Drizzle ORM and Zod, plus TanStack DB's React package and its router integration:

```bash filename="Terminal"
npm install @neon/realtime @neon/realtime-drizzle @neon/realtime-tanstack drizzle-orm zod
npm install @tanstack/react-db @tanstack/react-router-with-db
npm install -D @neon/config
```

Add a `neon.ts` that enables Managed Better Auth and Realtime on your branch:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1"

export default defineConfig({
  // Managed Better Auth signs users in. Each user's todos are scoped by their user id.
  auth: true,
  preview: {
    realtime: {
      allowedOrigins: ["http://localhost:3000"]
    }
  }
})
```

`allowedOrigins` lists the browser origins that can connect to Realtime, so add your app's origin when you deploy it. The [`neon.ts` reference](https://neon.com/docs/reference/neon-ts) covers the options.

Link the directory and run `neon deploy`, as in the [queries guide's setup](../guides/queries#setup). It writes `DATABASE_URL`, `NEON_REALTIME_URL`, `NEON_REALTIME_SECRET` and `NEON_AUTH_BASE_URL` to `.env.local`. If Realtime isn't ready before the deploy stops waiting, run `neon env pull` once it is.

Two more variables come from you. The browser needs the Realtime URL, and Vite only exposes variables that start with `VITE_`. The Managed Better Auth server SDK needs a cookie secret of at least 32 characters:

```bash filename="Terminal"
echo 'VITE_NEON_REALTIME_URL=$NEON_REALTIME_URL' >> .env.local
printf '\nNEON_AUTH_COOKIE_SECRET=%s\n' "$(openssl rand -base64 32)" >> .env.local
```

Vite expands `$NEON_REALTIME_URL` when it loads the file, so the browser URL follows the server variable after each `neon env pull`. It also inlines the value into the server build, so server rendering and the browser create the client with the same URL. `NEON_REALTIME_SECRET` never gets a `VITE_` prefix. The browser only ever sees the URL and sealed queries.

## Defining queries

Define each live query once, in server code. You run it to render the page on the server and seal it for the browser to subscribe to, so both get the same rows.

### Define the schema

Define your database schema. In this example, we're using Drizzle and defining a single table:

```ts filename="src/schema.ts"
import { boolean, index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core"

export const todos = pgTable(
  "realtime_todos",
  {
    // Generated in the browser, so an optimistic insert already has its key.
    id: uuid("id").primaryKey(),
    // The Managed Better Auth user id. Set on the server only; never sent to the browser.
    userId: text("user_id").notNull(),
    title: text("title").notNull(),
    completed: boolean("completed").notNull().default(false),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
  },
  (t) => [index("realtime_todos_user_id_idx").on(t.userId)]
)
```

### Define the live query

We then [define a query](../guides/queries). `db` is a Drizzle client over a node-postgres pool, in `src/db.server.ts`:

```ts filename="src/todos.server.ts"
import { eq, sql } from "drizzle-orm"

import { db } from "./db.server"
import { todos } from "./schema"

// One query for both the SSR rows and the sealed live query, so they match.
// Realtime matches each result column to its key by name, so `createdAt` gets
// an SQL alias (the column is `created_at`). `mapWith` keeps it a `Date`.
export const selectTodos = (userId: string) =>
  db
    .select({
      id: todos.id,
      title: todos.title,
      completed: todos.completed,
      createdAt: sql<Date>`${todos.createdAt}`.mapWith(todos.createdAt).as("createdAt")
    })
    .from(todos)
    .where(eq(todos.userId, userId))

// The row shape the browser sees, inferred from the query.
export type Todo = Awaited<ReturnType<typeof selectTodos>>[number]
```

The query has no `ORDER BY`, because the collection stores rows by key and doesn't keep their order. The page sorts them when it [queries the collection](https://neon.com/docs/realtime/examples/tanstack#render-the-collection). `userId` always comes from the server session, never from the browser. This `WHERE` is what keeps each user's todos separate.

## Sealing queries

Seal the query on the server, for the user in the session. The browser can subscribe to a sealed query, but it can't read or change it, as the queries guide explains in [sealing queries](../guides/queries#sealing-queries).

### Create the Realtime server

The Realtime server, from [`createRealtime()`](../sdks/typescript/backend#backend-createrealtime), holds the secret and seals queries. It should be created and then used in your trusted server code:

```ts filename="src/realtime.server.ts"
import { createRealtime } from "@neon/realtime/server"
import { drizzleAdapter } from "@neon/realtime-drizzle"

import { env, postgresDatabaseName } from "./env.server"

export const realtime = createRealtime({
  secret: env.realtime.secret,
  db: postgresDatabaseName,
  adapter: drizzleAdapter()
})
```

The `.server.ts` suffix keeps the file out of the browser bundle, as [the SSR guide explains](../guides/ssr#keep-secrets-on-the-server).

### Authorize with the session

TanStack Start mounts [Managed Better Auth](https://neon.com/docs/auth/overview) on your app's own origin, so server code reads the session from its cookie and the browser holds no token. Check the session in middleware, on the server, before you read, seal or write anything:

```ts filename="src/auth/auth.functions.ts"
import { createMiddleware } from "@tanstack/react-start"
import { setResponseStatus } from "@tanstack/react-start/server"
import { z } from "zod"

// The data boundary: every todo server function uses this, whatever the
// route guards do. The page sends the user id it was loaded for, so a session
// for another user (signed in from another tab) counts as signed out. The
// schema is loose, so the function's own fields reach its validator.
export const requireUser = createMiddleware({ type: "function" })
  .middleware([sessionMiddleware])
  .validator(z.looseObject({ userId: z.string() }))
  .server(({ next, context, data }) => {
    if (context.user?.id !== data.userId) {
      setResponseStatus(401)
      throw new Error("UNAUTHENTICATED")
    }
    return next({ context: { user: context.user } })
  })
```

Every server function that reads, seals or writes todos uses `requireUser`. Signed out or signed in as someone else, it responds with a 401 and throws `UNAUTHENTICATED`, which the collection [handles in the browser](https://neon.com/docs/realtime/examples/tanstack#define-the-collection). `sessionMiddleware`, in the same file, reads the session from the request's cookies, and `getSessionUser` gives the [route guards](https://neon.com/docs/realtime/examples/tanstack#keep-signed-in-pages-private) the user or `null`.

The rest of `src/auth/` is Managed Better Auth setup: the server, the `/api/auth` proxy, the browser client and the prebuilt sign-in UI, as in the [Managed Better Auth TanStack Router quick start](https://neon.com/docs/auth/quick-start/tanstack-router). `auth.server.ts` stands in for the Managed Better Auth adapter for TanStack Start, which isn't out yet. The SSR guide [builds the same server](../guides/ssr#send-both-to-the-browser) in `src/backend/auth.ts`.

### Seal in a server function

Expose the sealed query from a server function, as in [using server functions](../guides/queries#using-server-functions). `refreshTodosQuery` requires a signed-in user and seals `selectTodos()` for them. The browser calls it to [renew the sealed query](../guides/queries#renewing-sealed-queries) before it expires, so it has to seal exactly the same query:

```ts filename="src/todos.functions.ts"
import { createServerFn } from "@tanstack/react-start"

import { requireUser } from "./auth/auth.functions"
import { realtime } from "./realtime.server"
import { selectTodos } from "./todos.server"

// Every function requires a signed-in user and only touches that user's rows.
// Anything that returns rows or a sealed query is POST, so it's never cached.

// Re-seals the live query before it expires.
export const refreshTodosQuery = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .handler(({ context }) => realtime.seal({ query: selectTodos(context.user.id) }))
```

## Server-side rendering

TanStack Start renders the first request on the server. To put the user's rows in that HTML and keep them live in the browser:

1. read and seal the query in one server function
2. call it from a route loader, and seed a TanStack DB collection with the rows
3. let `routerWithDbClient()` carry the collection to the browser in the HTML

The SSR guide covers the pattern in [with TanStack DB](../guides/ssr#with-tanstack-db).

### Read and seal in one server function

Run the query and seal it in the same server function, so the rows and the sealed query match. This is [return the sealed query and initial results](../guides/ssr#return-the-sealed-query-and-initial-results) as a TanStack Start server function. Add it to `src/todos.functions.ts`, which already imports everything it uses:

```ts filename="src/todos.functions.ts"
// The page's rows, plus a sealed live query for exactly the same rows.
export const loadTodos = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .handler(async ({ context }) => {
    const [rows, query] = await Promise.all([
      selectTodos(context.user.id),
      realtime.seal({ query: selectTodos(context.user.id) })
    ])
    return { rows, query }
  })
```

[`realtime.seal()`](../sdks/typescript/backend#backend-realtimeserverseal) returns a typed [`SealedLiveQuery<Todo>`](../sdks/typescript/backend#backend-sealedlivequery), so the row type flows through to the collection and the page.

### Keep signed-in pages private

A server-rendered page carries the user's rows and a sealed query, which is a [bearer token](../guides/queries#sealing-queries). So load the session in the root route, and stop shared caches from storing the page:

```tsx filename="src/routes/__root.tsx"
import { createRootRouteWithContext } from "@tanstack/react-router"

import { getSessionUser } from "../auth/auth.functions"
import type { RouterContext } from "../router"

export const Route = createRootRouteWithContext<RouterContext>()({
  // Runs on every navigation, so the signed-in user is always current. During
  // SSR it runs in-process with the request's cookies.
  beforeLoad: async () => ({ user: await getSessionUser() }),
  // Pages carry the user's rows, so no shared cache may store them.
  headers: () => ({ "Cache-Control": "private, no-store", Vary: "Cookie" })
})
```

Then put the signed-in pages under a layout route that sends signed-out visitors to sign-in:

```tsx filename="src/routes/_authed.tsx"
import { createFileRoute, redirect } from "@tanstack/react-router"

// Signed-in pages. UX only: every server function checks `requireUser` too.
export const Route = createFileRoute("/_authed")({
  beforeLoad: ({ context }) => {
    if (!context.user) {
      throw redirect({
        to: "/auth/$path",
        params: { path: "sign-in" },
        // An SSR redirect skips the root route's `headers`.
        headers: { "Cache-Control": "private, no-store", Vary: "Cookie" }
      })
    }
    return { user: context.user }
  }
})
```

`beforeLoad` returns the signed-in `user`, so the routes below it get a user that's never `null`.

### Create a `DbClient` per router

A TanStack DB `DbClient` holds the collections, so on the server it has to belong to one request. Create it in `getRouter()`, which TanStack Start calls once per server request and once per page load in the browser. Create the Realtime client next to it and pass it to the `DbClient` as a dependency, so collections can read it:

```tsx filename="src/router.tsx"
import { createRealtimeClient } from "@neon/realtime/client"
import { drizzleParsers } from "@neon/realtime-drizzle/client"
import { DbClient } from "@tanstack/react-db"
import { createRouter } from "@tanstack/react-router"
import { routerWithDbClient } from "@tanstack/react-router-with-db"

import { routeTree } from "./routeTree.gen"

export interface RouterContext {
  readonly dbClient: DbClient;
}

// Runs once per SSR request and once per page load in the browser.
export function getRouter() {
  // Vite inlines this into the server build too, so SSR and the browser agree.
  const url = import.meta.env.VITE_NEON_REALTIME_URL
  if (!url) {
    throw new Error("VITE_NEON_REALTIME_URL is not set. See the README setup.")
  }
  // Collections read this with `db.requireDependency("realtime")`. On the
  // server it never connects: sync only starts in the browser.
  const realtime = createRealtimeClient({
    url,
    // Decode `date` and zone-less `timestamp` columns as Drizzle does.
    // This app has neither, but most Drizzle apps do
    parsers: { ...drizzleParsers }
  })
  const dbClient = new DbClient({ realtime })
  const router = createRouter({
    routeTree,
    context: { dbClient },
    scrollRestoration: true
  })
  // Snapshots the collections loaders filled on the server, and restores them
  // in the browser before the first render.
  return routerWithDbClient(router, dbClient)
}
```

- no collection is shared between users, because each request and each page load gets its own `DbClient`, as in [create a `DbClient` per router](../guides/ssr#create-a-dbclient-per-router). Sign-in and sign-out are full page loads, which drop the browser's `DbClient` and the previous user's rows with it. See [when the session changes](../guides/ssr#when-the-session-changes)
- [`drizzleParsers`](../sdks/typescript/drizzle#drizzle-client-drizzleparsers) parses live values the way Drizzle does, so live rows have the same types as the rows the server rendered. See [keep row shapes identical](../guides/ssr#keep-row-shapes-identical)
- `routerWithDbClient()` wraps the app in TanStack DB's provider, so components get this `DbClient` from `useDbClient()`. It also snapshots the collections that loaders seeded on the server into the HTML, and restores them in the browser before the first render
- `RouterContext` puts `dbClient` on route context, where the route loader reads it

### Seed the collection in a loader

In the route loader, call the server function and seed the user's collection with its rows. Loaders also run in the browser on client-side navigation, so they call a server function rather than importing server modules:

```tsx filename="src/routes/_authed/index.tsx"
import { createFileRoute } from "@tanstack/react-router"

import { todosCollection } from "../../todos.collection"
import { loadTodos } from "../../todos.functions"

export const Route = createFileRoute("/_authed/")({
  // Don't refetch on a navigation back here while the collection is live.
  // No visible effect until the app has a second page.
  staleTime: Infinity,
  // Fills the router's DbClient. On the server, routerWithDbClient snapshots
  // these rows into the HTML and restores them in the browser before render.
  loader: async ({ context }) => {
    const { rows, query } = await loadTodos({ data: { userId: context.user.id } })
    // A no-op if this user's collection already exists.
    context.dbClient.collection(todosCollection(context.user.id, query), { initialData: rows })
    return { query }
  },
  component: TodosPage
})
```

- `todosCollection()` returns the collection's descriptor, which you [define](https://neon.com/docs/realtime/examples/tanstack#define-the-collection) for client-side reactivity
- `context.dbClient.collection(descriptor, { initialData: rows })` creates the collection with the rows, without starting sync. If the collection already exists, the call reuses it and ignores `initialData`, so the live rows stay
- the loader returns only `{ query }`. The rows travel to the browser in the collection

## Client-side reactivity

In the browser, a TanStack DB collection syncs the live query's rows, and components query the collection locally. The reactivity guide explains [why a collection](../guides/reactivity#tanstack-db) suits live data.

### Define the collection

Define the collection as a descriptor, with the two-argument `collectionOptions(id, factory)` around [`realtimeCollectionOptions()`](../sdks/typescript/tanstack-db#tanstack-db-realtimecollectionoptions). The descriptor is cheap to build, so the loader and the page both build it, and the shared `id` resolves both to the collection the loader seeded. The factory runs once per `DbClient`, and reads that `DbClient`'s Realtime client:

```ts filename="src/todos.collection.ts"
import type { RealtimeClient, SealedLiveQuery } from "@neon/realtime/client"
import { realtimeCollectionOptions } from "@neon/realtime-tanstack"
import { collectionOptions } from "@tanstack/react-db"

import { leaveIfSignedOut } from "./auth/session-lost"
import { refreshTodosQuery } from "./todos.functions"
import type { Todo } from "./todos.server"

// A cheap descriptor, built by the loader and the page alike. The factory runs
// once per DbClient, with the Realtime client `getRouter` gave that DbClient.
export function todosCollection(userId: string, query: SealedLiveQuery<Todo>) {
  const id = `todos:${userId}`
  return collectionOptions(id, (db) =>
    realtimeCollectionOptions({
      id,
      query,
      client: db.requireDependency<RealtimeClient>("realtime"),
      getKey: (todo) => todo.id,
      // Never garbage-collect while the page is open. A collection rebuilt
      // later would start empty, from this long-expired sealed query, and stay
      // `stale` until a refresh replaced it.
      gcTime: 0,
      refreshQuery: () => refreshTodosQuery({ data: { userId } }).catch(leaveIfSignedOut)
    })
  )
}
```

- `realtimeCollectionOptions()` takes the sealed `query`, the Realtime `client` and `getKey`, and syncs the collection from the subscription. Other TanStack DB options, like `gcTime`, pass through. The [config reference](../sdks/typescript/tanstack-db#tanstack-db-realtimecollectionconfig) lists them all
- `refreshQuery` returns a fresh sealed query for the same query. The collection calls it before the current one expires and renews the subscription in place, keeping its rows. See [`refreshQuery`](../guides/reactivity#refreshquery)
- `gcTime: 0` turns off garbage collection in TanStack DB, which differs from TanStack Query, where `0` collects at once

If the session is gone or belongs to another user, the server function fails with `UNAUTHENTICATED`, and `leaveIfSignedOut`, from `src/auth/session-lost.ts`, does a full page load of `/`. The SSR guide explains [when the session changes](../guides/ssr#when-the-session-changes).

### Render the collection

Query the collection with TanStack DB's `useLiveQuery()`, and render its rows straight away, without waiting for `isReady`. The seeded rows are there for the first render, on the server and in the browser. Add the page component to `src/routes/_authed/index.tsx`, with one more import:

```tsx filename="src/routes/_authed/index.tsx"
import { useLiveQuery } from "@tanstack/react-db"

function TodosPage() {
  const { query } = Route.useLoaderData()
  const { user } = Route.useRouteContext()
  // Same id as the loader's, so this resolves to the collection it filled.
  const descriptor = todosCollection(user.id, query)
  // `isReady` turns true when Realtime sends its first complete result, and
  // stays true while it reconnects or renews the query. The SSR rows are on
  // screen before that.
  const { data: todos, isReady } = useLiveQuery({
    query: (q) =>
      q
        .from({ todo: descriptor })
        .orderBy(({ todo }) => todo.createdAt, "desc")
        .orderBy(({ todo }) => todo.id, "desc")
  })

  return (
    <main>
      <output>{isReady ? "live" : "connecting"}</output>

      <ul aria-live="polite">
        {todos.map((todo) => (
          <li key={todo.id}>
            <span>{todo.title}</span>
          </li>
        ))}
      </ul>
    </main>
  )
}
```

On the first request, the rows go from the server's query to the live subscription in four steps:

1. on the server, the loader seeds the collection and `useLiveQuery()` reads it, so the HTML has the user's rows. Nothing subscribes on the server
2. `routerWithDbClient()` snapshots the collection into the HTML. In the browser, it restores the rows before the first render, so hydration matches the server's markup with no loading flash
3. after hydration, `useLiveQuery()` starts the collection's sync, which subscribes with the sealed query from the loader
4. the first result replaces the seeded rows in one step, and `isReady` turns true. Any change committed since the server read the rows is in that result

`useLiveQuery()` sorts the rows in the browser, newest first, because the live query has no `ORDER BY`. See [query the collection](../guides/reactivity#query-the-collection) for more local queries.

## Optimistic mutations

Write to the collection, and TanStack DB applies each change at once and calls your mutation handler. The handler sends the change to a server function, which writes it in one SQL statement and returns the transaction ID from that same statement. The handler then waits for that ID to come back on the subscription, so the optimistic row hands over to the synced one in one step. The mutations guide explains [how optimistic mutations work](../guides/mutations#how-optimistic-mutations-work).

### Write to the collection

Call `insert()`, `update()` and `delete()` on the collection. Each applies at once and returns a TanStack DB transaction, which rejects if the write rolls back. Here's the page component with writes. It replaces the component, and the `@tanstack/react-db` and `../../todos.collection` imports, from [render the collection](https://neon.com/docs/realtime/examples/tanstack#render-the-collection):

```tsx filename="src/routes/_authed/index.tsx"
import { useDbClient, useLiveQuery, type Transaction } from "@tanstack/react-db"
import { useState, type FormEvent } from "react"

import { NotSyncedYetError, todosCollection } from "../../todos.collection"

type Notice = { tone: "error" | "info"; text: string }

function TodosPage() {
  const { query } = Route.useLoaderData()
  const { user } = Route.useRouteContext()
  // Same id as the loader's, so this resolves to the collection it filled.
  const descriptor = todosCollection(user.id, query)
  const collection = useDbClient().collection(descriptor)
  // `isReady` turns true when Realtime sends its first complete result, and
  // stays true while it reconnects or renews the query. The SSR rows are on
  // screen before that.
  const { data: todos, isReady } = useLiveQuery({
    query: (q) =>
      q
        .from({ todo: descriptor })
        .orderBy(({ todo }) => todo.createdAt, "desc")
        .orderBy(({ todo }) => todo.id, "desc")
  })
  const [notice, setNotice] = useState<Notice | null>(null)

  // Changes apply optimistically. If one fails, TanStack DB rolls it back and
  // the reason shows here.
  function track(tx: Transaction) {
    setNotice(null)
    tx.when("settled").catch((cause: unknown) =>
      setNotice(
        cause instanceof NotSyncedYetError
          ? { tone: "info", text: "Saved. It will appear when live updates reconnect." }
          : { tone: "error", text: `Couldn't save that change: ${cause instanceof Error ? cause.message : String(cause)}` }
      )
    )
  }

  function addTodo(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    const form = event.currentTarget
    const title = String(new FormData(form).get("title") ?? "").trim()
    if (!title) return
    form.reset()
    track(
      collection.insert({
        id: crypto.randomUUID(),
        title,
        completed: false,
        createdAt: new Date()
      })
    )
  }

  return (
    <main>
      <output>{isReady ? "live" : "connecting"}</output>

      <form onSubmit={addTodo}>
        <input aria-label="Todo title" maxLength={200} name="title" placeholder="What needs doing?" required />
        <button type="submit">Add item</button>
      </form>

      {notice ? <p role={notice.tone === "error" ? "alert" : "status"}>{notice.text}</p> : null}

      <ul aria-live="polite">
        {todos.map((todo) => (
          <li key={todo.id}>
            <label>
              <input
                aria-label={`Mark ${todo.title} as ${todo.completed ? "incomplete" : "complete"}`}
                checked={todo.completed}
                disabled={todo.$hasPendingWrites}
                onChange={() =>
                  track(
                    collection.update(todo.id, (draft) => {
                      draft.completed = !draft.completed
                    })
                  )
                }
                type="checkbox"
              />
              <span>{todo.title}</span>
            </label>
            <button
              aria-label={`Delete ${todo.title}`}
              disabled={todo.$hasPendingWrites}
              onClick={() => track(collection.delete(todo.id))}
              type="button"
            >
              Delete
            </button>
          </li>
        ))}
      </ul>
    </main>
  )
}
```

- `useDbClient().collection(descriptor)` returns the collection the loader seeded, to write to
- the insert sets `id` and a provisional `createdAt` in the browser, so the new row has its final key and sorts to the top straight away. The synced row brings the server's timestamp
- `track` waits for each transaction's `when("settled")` promise, and shows a notice if the change rolls back. A [`NotSyncedYetError`](https://neon.com/docs/realtime/examples/tanstack#send-writes-to-the-server) means the write committed but its change didn't come back in time, so the notice says it's saved
- `$hasPendingWrites` is `true` while a row has a pending optimistic change, which disables its checkbox and Delete button, so you don't start a new change on a todo whose last change isn't confirmed yet. TanStack DB runs handlers concurrently, so a toggle or delete sent straight after an insert could reach the database before the insert commits, match no rows and be lost

### Send writes to the server

Add `onInsert`, `onUpdate` and `onDelete` handlers to `realtimeCollectionOptions()` in `src/todos.collection.ts`, after `refreshQuery`. TanStack DB calls each one once per transaction, with all of its mutations, so each handler sends one batch to its server function. If the write changed rows, the handler waits for its transaction ID:

```ts filename="src/todos.collection.ts"
refreshQuery: () => refreshTodosQuery({ data: { userId } }).catch(leaveIfSignedOut),
// One server call per transaction, with all of its mutations. Each also
// sends `userId`, so the server refuses writes from a page loaded for
// another user.
onInsert: async ({ transaction, collection }) => {
  const { txid } = await createTodos({
    data: {
      userId,
      batch: transaction.mutations.map(({ modified: { id, title, completed } }) => ({ id, title, completed }))
    }
  }).catch(leaveIfSignedOut)
  if (txid) await collection.utils.awaitTxId(txid, ECHO_TIMEOUT_MS).catch(notSyncedYet)
},
onUpdate: async ({ transaction, collection }) => {
  const { txid } = await updateTodos({
    data: {
      userId,
      // The server keeps only `title` and `completed` from `changes`.
      batch: transaction.mutations.map(({ key, changes }) => ({ id: key, changes }))
    }
  }).catch(leaveIfSignedOut)
  if (txid) await collection.utils.awaitTxId(txid, ECHO_TIMEOUT_MS).catch(notSyncedYet)
},
onDelete: async ({ transaction, collection }) => {
  const { txid } = await deleteTodos({
    data: { userId, batch: transaction.mutations.map(({ key }) => key) }
  }).catch(leaveIfSignedOut)
  if (txid) await collection.utils.awaitTxId(txid, ECHO_TIMEOUT_MS).catch(notSyncedYet)
}
```

Then add what the handlers use at the top level of the file, and import the three write server functions next to `refreshTodosQuery`:

```ts filename="src/todos.collection.ts"
import { createTodos, deleteTodos, refreshTodosQuery, updateTodos } from "./todos.functions"

// How long a write waits for its own change to come back over Realtime. Keep it
// short: while a handler waits, TanStack DB holds back the collection's synced
// changes, including other tabs' writes.
const ECHO_TIMEOUT_MS = 10_000

// The write committed, but its change didn't come back over Realtime in time,
// for example while live updates reconnect. TanStack DB still rolls the change
// back, and it shows again once Realtime catches up.
export class NotSyncedYetError extends Error {}

function notSyncedYet(cause: unknown): never {
  throw new NotSyncedYetError("Saved, but not synced yet", { cause })
}
```

- [`collection.utils.awaitTxId(txid, timeout)`](../sdks/typescript/tanstack-db#tanstack-db-realtimecollectionutilsawaittxid) waits until the subscription has delivered that transaction's changes. While a handler runs, TanStack DB holds back synced changes, so the optimistic row hands over to the synced one in one step
- TanStack DB rolls the change back if the server function throws, the wait times out, or the subscription errors or closes. The mutations guide covers [handlers with TanStack DB collections](../guides/mutations#with-tanstack-db-collections)
- `awaitTxId()` keeps waiting while the subscription reconnects or waits for a renewed sealed query, and the collection holds back synced changes while it waits. Keep the timeout short: `ECHO_TIMEOUT_MS` is 10 seconds, as in the guides
- once a handler has a txid, the write has committed, so `notSyncedYet` turns any failed wait into a `NotSyncedYetError`. The change still rolls back, but the page says it's saved rather than showing an error, and the change shows again when Realtime catches up

### Return the txid from the server

Add one server function per mutation type to `src/todos.functions.ts`, with the imports they add. Each function writes its whole batch in one SQL statement, and the statement's `RETURNING` clause includes `pg_current_xact_id()`, so it returns the transaction ID without another database round trip:

```ts filename="src/todos.functions.ts"
import { and, eq, inArray, sql } from "drizzle-orm"

import { db } from "./db.server"
import { todos } from "./schema"
import { newTodosInput, todoIdsInput, todoUpdatesInput } from "./todos.schemas"

type WriteResult = { readonly txid: string | null }

const txid = sql<string>`pg_current_xact_id()::text`

const writeResult = (row?: { txid: string }): WriteResult => ({
  txid: row?.txid ?? null
})

// Each write sends a whole TanStack DB batch in one SQL statement and returns
// its Postgres transaction id, or `null` if no row changed (for example, an id
// that's already gone).
export const createTodos = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .validator(newTodosInput)
  .handler(async ({ data: { batch }, context }) => {
    const [created] = await db
      .insert(todos)
      .values(batch.map((todo) => ({ ...todo, userId: context.user.id })))
      .returning({ txid })
    return writeResult(created)
  })

export const updateTodos = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .validator(todoUpdatesInput)
  .handler(async ({ data: { batch }, context }) => {
    const changed = batch.filter(({ changes }) =>
      Object.values(changes).some((value) => value !== undefined)
    )
    if (changed.length === 0) return writeResult()

    const titleCases = changed.flatMap(({ id, changes }) =>
      changes.title === undefined ? [] : [sql`WHEN ${todos.id} = ${id} THEN ${changes.title}`]
    )
    const completedCases = changed.flatMap(({ id, changes }) =>
      changes.completed === undefined ? [] : [sql`WHEN ${todos.id} = ${id} THEN ${changes.completed}`]
    )

    const [updated] = await db
      .update(todos)
      .set({
        ...(titleCases.length > 0
          ? { title: sql<string>`CASE ${sql.join(titleCases, sql.raw(" "))} ELSE ${todos.title} END` }
          : {}),
        ...(completedCases.length > 0
          ? { completed: sql<boolean>`CASE ${sql.join(completedCases, sql.raw(" "))} ELSE ${todos.completed} END` }
          : {})
      })
      .where(
        and(
          inArray(
            todos.id,
            changed.map(({ id }) => id)
          ),
          eq(todos.userId, context.user.id)
        )
      )
      .returning({ txid })
    return writeResult(updated)
  })

export const deleteTodos = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .validator(todoIdsInput)
  .handler(async ({ data: { batch }, context }) => {
    const [deleted] = await db
      .delete(todos)
      .where(and(inArray(todos.id, batch), eq(todos.userId, context.user.id)))
      .returning({ txid })
    return writeResult(deleted)
  })
```

- each call writes one TanStack DB transaction's batch in one SQL statement, so there's one txid to wait for. A single statement is its own Postgres transaction, so `pg_current_xact_id()` returns the ID of the transaction that made the change. See [returning the txid from your backend](../guides/mutations#returning-the-txid-from-your-backend)
- the query casts `txid` to `text`, because the collection waits for a decimal string. Every row a statement returns carries the same txid, so `writeResult` reads the first one. If no row changed, there's nothing to wait for and nothing to roll back, so it returns `{ txid: null }`
- `updateTodos` sets each column with a `CASE` on the row's `id`, so a batch of different changes is still one `UPDATE`. It leaves out a column no change touches, and skips the query when nothing changed, because Drizzle rejects an empty `set`
- the server functions take the user from the session, never from the browser. `requireUser` only compares the browser's `userId` with the session's, and the zod input schemas in `src/todos.schemas.ts` strip unknown keys, so a row's `userId` can't come from the browser
- `updateTodos` and `deleteTodos` scope their `WHERE` to the session's user, so one user can't change another's rows

## Next steps

- read the guides on [reactivity](../guides/reactivity), [optimistic mutations](../guides/mutations) and [server-side rendering](../guides/ssr) for the concepts behind each step
- look up every `realtimeCollectionOptions()` option in the [TanStack DB section of the SDK reference](../sdks/typescript/tanstack-db)
- see the [Next.js example](./nextjs), which reads and seals in a Server Component and subscribes in a Client Component
- browse the [full source on GitHub](https://github.com/neondatabase/examples/tree/main/realtime/with-tanstack)

---

## Related docs (Examples)

- [Overview](https://neon.com/docs/realtime/examples/overview)
- [Next.js](https://neon.com/docs/realtime/examples/nextjs)
- [Mastra](https://neon.com/docs/realtime/examples/mastra)
- [Drizzle](https://neon.com/docs/realtime/examples/drizzle)
- [Kysely](https://neon.com/docs/realtime/examples/kysely)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/realtime/examples/tanstack"}` to https://feedback.neon.tech/ (no auth required).
