---
name: lunora-realtime
description: Wires Lunora's live data into a client. Use for `LunoraClient`/`LunoraProvider`,
    reactive `useQuery`/`useSubscription`, `useMutation` with optimistic updates,
    pagination, connection status, the React/Vue/Solid/Svelte/Angular/React Native
    adapters, and the `@lunora/db` TanStack binding.
---

# Lunora Realtime

Consume Lunora functions reactively from the client. Queries are live
subscriptions over WebSocket — a `useQuery` re-renders the instant a mutation
changes the rows it reads — and mutations can paint optimistically with
automatic rollback.

## When to Use

- Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte, Angular,
  React Native/Expo, or an Astro/Nuxt meta-framework).
- Adding optimistic updates, pagination, or presence to the UI.
- Choosing between live hooks and the `@lunora/db` collection layer.

## When Not to Use

- Writing the server functions themselves — that's `lunora-functions`.
- Initial project/provider scaffolding — that's `lunora-quickstart`.

## Provider Setup

Create the `LunoraClient` once at module scope and wrap the app. The client owns
the WebSocket, the optimistic cache, and the offline queue.

```tsx
import { LunoraClient } from "@lunora/client";
import { LunoraProvider } from "@lunora/react";

const url = (import.meta.env.VITE_LUNORA_URL as string | undefined) ?? globalThis.location.origin;
const client = new LunoraClient({ url });

// <LunoraProvider client={client}>…</LunoraProvider>
```

Vue / Solid / Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
`@lunora/svelte`; the hook names and semantics below mirror across them.

Two adapters differ in shape:

- **`@lunora/angular`** is signal-based rather than hook-based: register with
  `provideLunora(...)`, read the client via `injectLunoraClient()`, and use
  `liveQuery(...)` / `mutate(...)` / `connectionStatus(...)` in place of the
  hooks below.
- **`@lunora/react-native`** re-exports all of `@lunora/react` and adds
  `createLunoraClient` (plus `@lunora/react-native/auth` for the better-auth
  Expo bridge) — build the client with that instead of `new LunoraClient`.

For SSR meta-frameworks, `@lunora/astro` and `@lunora/nuxt` compose Lunora into
the server (Nitro for Nuxt) and ship reactive-loader server helpers.

## Live Queries

`useQuery(reference, args)` opens a subscription and returns the value, or
`undefined` while it loads. The reference comes from codegen
(`api.<file>.<name>`).

```tsx
import { useQuery } from "@lunora/react";

import { api } from "../../lunora/_generated/api";
import type { Doc } from "../../lunora/_generated/dataModel";

const todos = useQuery(api.todos.list, {}) as Doc<"todos">[] | undefined;
```

- `undefined` means "loading" — render a skeleton/spinner for it.
- The subscription tears down on unmount and re-runs only when `args` change or
  the underlying rows change. Keep `args` narrow so a write elsewhere doesn't
  re-push unrelated data (see `lunora-performance-audit`).
- `useSubscription` is the lower-level primitive for streaming subscriptions;
  `usePreloadedQuery` + `lunoraQueryOptions` support SSR/preload handoff via
  `@lunora/react/server`.

## Authorization & Live Queries

**Live queries are identity-aware.** At the WebSocket upgrade the runtime
stamps the caller's verified identity onto the socket (from the server-minted
`x-lunora-userid` / `x-lunora-identity` headers, which a client cannot forge).
Every subscription re-run, shape resolution, and poke-driven refresh executes
under that socket's own identity, passed by value so a concurrent RPC can't
clobber it.

Practically, this means:

- `.use(rls(...))` and `ctx.auth.userId` work the same in a subscribed query as
  in a one-shot read. Shape subscriptions AND-merge the shape predicate with
  the table's RLS read base-where, so the membership query the poke protocol
  runs is RLS-correct by construction — never the client's word for it.
- An **anonymous** socket carries no identity, so an RLS/`ctx.auth` query fails
  closed (empty/denied) rather than leaking another user's rows.
- **Token expiry is enforced on the socket.** When the resolved credential
  carries an expiry, the DO sends a `TOKEN_EXPIRED` error frame and closes with
  code `4001` at the next send at or after that instant. `LunoraClient`
  reconnects automatically and re-resolves a fresh identity — but surface it in
  the UI if a re-login is required.

You can still scope data structurally when it fits the domain — `.shardBy(userId)`
(or tenant/room) partitions state so a subscription is narrow by construction,
and explicit query args keep subscriptions cheap (see the args-scoping note
above). Prefer those for _performance_; use `rls()` / `ctx.auth` for
_authorization_. They compose.

## Mutations + Optimistic Updates

`useMutation(reference)` returns `{ mutate, pending }`. Pass an `optimistic`
callback to paint the next state immediately; if the server rejects the call the
runtime rolls the cache back automatically.

```tsx
import { useMutation } from "@lunora/react";

import type { Doc, Id } from "../../lunora/_generated/dataModel";

const { mutate: add, pending } = useMutation(api.todos.add);

await add(
    { text },
    {
        optimistic: (current) => {
            const list = (current as Doc<"todos">[] | undefined) ?? [];
            const provisional: Doc<"todos"> = {
                _id: `optimistic_${Date.now()}` as Id<"todos">,
                _creationTime: Date.now(),
                text,
                done: false,
                createdAt: Date.now(),
            };
            return [provisional, ...list];
        },
    },
);
```

- The `optimistic` callback receives the current cached value and returns the
  provisional one. When the server delta arrives it replaces the optimistic
  entry; on failure the cache reverts.
- `pending` is `true` while the call is in flight — disable the submit button
  with it.
- **Offline queue:** mutations made while disconnected are queued by
  `LunoraClient` and replayed on reconnect (client-id-keyed, so they aren't
  double-applied).

## Pagination, Connection, Presence

- `usePaginatedQuery` / `useInfiniteQuery` — cursor pagination over a query that
  ends in `.paginate(...)` on the server.
- `useConnectionStatus` — live socket state for an offline/reconnecting banner.
- `usePresence` — who's-here + heartbeat (pairs with the `presence` registry
  item).
- `useAuth` + the `Authenticated` / `Unauthenticated` / `AuthLoading` gates —
  see `lunora-setup-auth`.

## `@lunora/db` — TanStack DB Collections

For richer client state (indexed local collections, cross-query joins, a durable
offline-transactions outbox), use `@lunora/db` instead of raw hooks. Scaffold
with `vis generate lunora-collections` (wires `defineCollections` from your
schema + functions into live TanStack DB collections). Reach for it when the app
needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery`
/`useMutation` are enough for straightforward live lists.

Call `defineCollections` **once** at module scope and treat the returned
collections as the single source of truth for each table. Don't mirror rows into
a parallel store, and never build derived indexes (trees, search, undo captures)
from a copy — optimistic writes and sync deltas land only on the Lunora
collection, so code reading a copy silently reads stale rows while `useLiveQuery`
renders fresh data.

## Common Pitfalls

1. **Creating `LunoraClient` inside a component.** It re-opens the socket every
   render — create it once at module scope.
2. **Treating `undefined` as empty.** `undefined` is "loading", `[]` is "loaded,
   empty" — branch on both.
3. **Broad query args.** A subscription keyed too broadly re-renders on
   unrelated writes; scope `args` to what the component shows.
4. **Optimistic shape drift.** The provisional value must match the query's
   element shape (including `_id`/`_creationTime`) or the UI flickers when the
   real delta lands.
5. **Two sources of truth for the same rows.** `defineCollections` more than once
   per table (or a parallel store of your own) mints copies that drift. Reads
   through `useLiveQuery` look fine, but derived indexes built from the copy can
   **miss rows** — rows written to the collection after the copy was taken never
   appear in the index — or **hold stale rows** — rows updated or deleted in the
   collection still show their old value. One instance, one collection per table.

## Checklist

- [ ] `LunoraClient` created once at module scope; app wrapped in the provider.
- [ ] Live reads use `useQuery`; `undefined` handled as loading.
- [ ] Writes use `useMutation`; `pending` disables submit; `optimistic` matches
      the row shape.
- [ ] Query `args` scoped narrowly to avoid over-broad re-renders.
- [ ] Pagination via `usePaginatedQuery`/`useInfiniteQuery` over `.paginate`.
- [ ] Considered `@lunora/db` if the app needs local indexes/joins or an outbox.
- [ ] `@lunora/db`: one `defineCollections` instance; no parallel copy of rows;
      derived indexes built from the same collection the UI renders.