Last updated:
@lunora/react-native is the React Native / Expo entry to Lunora. It
re-exports @lunora/react's data and auth surface:
useQuery, useMutation, useSubscription, useAuth, usePresence,
useConnectionStatus, <LunoraProvider> and the auth gates are react-dom-free
and touch no browser-only global, so they run unchanged on a phone.
The payment kit is not part of that surface. CheckoutButton,
CustomerPortalButton and useCheckout render a DOM <button> and navigate
with globalThis.location, neither of which exists in React Native, so they
live at @lunora/react/payment rather than on the root barrel — a native app
never imports them by accident. Drive a checkout from a native screen instead:
call the action that returns the provider's { url } (with useMutation) and
open it with Expo's Linking or WebBrowser.
On top of that it adds the two things a native app needs that a browser gives you for free:
- a durable offline queue backed by
AsyncStorage(React Native has no IndexedDB, which the browser client auto-probes), and - credentialed requests: the session is a bearer, attached explicitly to every HTTP RPC call and the WebSocket upgrade.
Both are wrapped up in createLunoraClient, plus a one-import better-auth Expo
bridge at @lunora/react-native/auth.
A complete example (auth, a live message list, optimistic + offline-safe sends) lives at
examples/expo.
Scaffold a new app
The expo template scaffolds a full Expo app (iOS, Android, and web) wired to a
Lunora worker backend, with auth and the live-chat example already in place:
lunora init my-app -t expoThen follow the generated README.md (create a D1 database, set AUTH_SECRET,
lunora codegen, and expo start). To add Lunora to an existing Expo app
instead, wire it by hand as below.
Install
pnpm add @lunora/react-native @lunora/react @tanstack/react-query react
npx expo install @react-native-async-storage/async-storageFor auth also add better-auth @better-auth/expo and
npx expo install expo-secure-store expo-web-browser expo-linking expo-constants expo-network.
Create the client
createLunoraClient is a thin wrapper over new LunoraClient(options). Pass
storage to persist the offline queue across restarts.
import AsyncStorage from "@react-native-async-storage/async-storage";
import { createLunoraClient } from "@lunora/react-native";
export const client = createLunoraClient({
url: process.env.EXPO_PUBLIC_LUNORA_URL!, // e.g. https://my-app.workers.dev
storage: AsyncStorage,
});Provide it
Mount <LunoraProvider> (re-exported from this package) inside a TanStack Query
provider, exactly as on the web.
import { LunoraProvider } from "@lunora/react-native";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { client } from "./lunora";
import { Chat } from "./Chat";
const queryClient = new QueryClient();
export default function App() {
return (
<QueryClientProvider client={queryClient}>
<LunoraProvider client={client}>
<Chat />
</LunoraProvider>
</QueryClientProvider>
);
}Live queries and mutations
The hooks are the React ones; only the host components change (View, Text,
FlatList instead of DOM elements).
import { useMutation, useQuery } from "@lunora/react-native";
import { FlatList, Text } from "react-native";
import { api } from "./lunora/_generated/api";
export function Chat() {
const messages = useQuery(api.messages.list, {});
const { mutate: send } = useMutation(api.messages.send);
return <FlatList data={messages ?? []} keyExtractor={(m) => m._id} renderItem={({ item }) => <Text>{item.text}</Text>} />;
}useQuery opens a live WebSocket subscription; send is optimistic and, thanks
to the AsyncStorage persistence, queued and retried when offline.
HTTP streams
useHttpStream (httpRoute.<verb>(path).stream() routes) runs on native, but
buffered: React Native's fetch is the whatwg-fetch polyfill, which
defines no response.body stream, so the client reads the whole payload through
response.text() and every chunk arrives together when the response lands
rather than as the handler yields it. Under react-native-web a real browser
fetch is in charge, so the chunks stream incrementally there.
To render a long route's chunks as they are written — tokens as a model emits
them — pass a fetch that exposes response.body; Expo's does:
import { fetch as expoFetch } from "expo/fetch";
import { createLunoraClient, withoutAmbientCookies } from "@lunora/react-native";
const client = createLunoraClient({ fetch: withoutAmbientCookies(expoFetch), url: process.env.EXPO_PUBLIC_LUNORA_URL! });A custom fetch skips the credentials: "omit" wrapper
createLunoraClient applies to the global one (see the warning above), so wrap
it in withoutAmbientCookies yourself — otherwise the native cookie jar
reintroduces the FORBIDDEN_ORIGIN loop. The client's fetch option feeds
client.httpStream and useHttpStream; a standalone
httpStream(route, args, { fetch }) call takes its own.
Local-first (shapes, custom mutators, TanStack DB)
Lunora's local-first tier — defineShape,
defineMutator, defineCollections, bindMutators, plus TanStack DB's useLiveQuery — runs on
React Native unchanged. One platform prerequisite:
Install a WebCrypto polyfill first. Every optimistic write mints a
client-side id through @tanstack/db's safeRandomUUID, which needs
crypto.randomUUID or crypto.getRandomValues. Hermes ships neither.
Without the polyfill @lunora/db throws at setup naming this; before that guard
existed the first write failed as an unhandled promise rejection with
No secure random number generator available — no UI error, and the row
never appeared.
npx expo install expo-crypto// Must be the FIRST import, before anything that reaches @lunora/db or @tanstack/db.
import "expo-crypto";
import { registerRootComponent } from "expo";
import App from "./App";
registerRootComponent(App);react-native-get-random-values works equally well if you are not on Expo.
Custom mutators bound with bindMutators are optimistic and rebased, not
offline-durable: they push straight through client.callMutator, so with the
server unreachable the write is rejected, the optimistic row rolls back, and
onWriteRejected fires. Only defineCollections drives the durable
@tanstack/offline-transactions outbox. Reach for defineCollections when a
write has to survive being made offline.
Authentication (better-auth + Expo)
The session is sent as a bearer token: the HTTP RPC and, on native, the live
socket's upgrade both carry it in the Authorization header (see
How auth reaches the live socket).
The better-auth Expo
plugin persists the session in SecureStore; expoBearerToken reads the token
out.
import { expoClient } from "@lunora/react-native/auth";
import { createAuthClient } from "better-auth/react";
import * as SecureStore from "expo-secure-store";
export const authClient = createAuthClient({
baseURL: process.env.EXPO_PUBLIC_LUNORA_URL!,
plugins: [expoClient({ scheme: "myapp", storage: SecureStore })],
});import AsyncStorage from "@react-native-async-storage/async-storage";
import { createLunoraClient } from "@lunora/react-native";
export const client = createLunoraClient({
url: process.env.EXPO_PUBLIC_LUNORA_URL!,
storage: AsyncStorage,
});Bridge the session into the client whenever it changes with setAuthToken. It
rides HTTP RPC as Authorization: Bearer …, and on native createLunoraClient
sends it as the WebSocket upgrade's Authorization header too (a sign-in
reconnects the socket to present it).
import { expoBearerToken } from "@lunora/react-native/auth";
import { useEffect } from "react";
import { authClient } from "./auth-client";
import { client } from "./lunora";
// inside a component that renders once the session is known:
const { data: session } = authClient.useSession();
// `expoBearerToken` is async since better-auth 1.7, and an async function is
// not a valid effect cleanup return — so kick off a promise instead. `cancelled`
// is load-bearing: two session changes in quick succession leave two reads in
// flight, and without it the slower one reinstates the previous session's token.
useEffect(() => {
let cancelled = false;
void (async () => {
const token = await expoBearerToken(authClient);
if (cancelled) return;
client.setAuthToken(token); // HTTP + native WS upgrade `Authorization: Bearer …`
})();
return () => {
cancelled = true;
};
}, [session]);On the server, add better-auth's expo() and bearer() plugins and read
the session from the request headers in resolveIdentity:
import { bearer } from "@lunora/auth/plugins";
import { expo } from "@better-auth/expo";
// authOptions.plugins: [expo(), bearer(), /* … */]
// authOptions.trustedOrigins: ["myapp://"]
// createWorker({
// // HTTP RPC and the native WebSocket upgrade both carry `Authorization`.
// resolveIdentity: async (request) => {
// const session = await auth.api.getSession({ headers: request.headers });
// return session?.user?.id ? { userId: session.user.id } : null;
// },
// });scheme in app.json, the expoClient({scheme}) call, and the server's trustedOrigins must all match.How auth reaches the live socket
Lunora's runtime enables a CSRF Origin-check by default: it rejects any
state-changing HTTP request or WebSocket upgrade that carries a Cookie but no
trusted Origin. React Native sends no Origin, so a cookie credential is
rejected once signed in. A bearer token is the credential instead: the HTTP
RPC sends Authorization: Bearer <token>, and on native the WebSocket upgrade
carries the same header (createLunoraClient adds it from setAuthToken), so
better-auth's bearer plugin resolves both in resolveIdentity. The bearer is
never sent in the URL. setWsToken is not for the session token: it sends its
value in the connect frame, which the server checks against the shared
LUNORA_WS_BEARER gate. Leave that variable unset for an Expo app: a shipped app
cannot hold the shared secret, and a session token does not match it, so a server
that sets it closes every Expo socket with 4003. Under react-native-web
the browser socket cannot set a header; the better-auth session cookie
authenticates it there, so serve the worker same-site with the web app.
Using a bearer does not on its own guarantee the absence of a Cookie
header. React Native has a real cookie jar — fetch is backed by the platform
HTTP stack (NSURLSession / OkHttp) and its shared cookie store — so the
Set-Cookie a better-auth sign-in returns is kept and re-attached to later
requests, and the guard then 403s every state-changing RPC with
FORBIDDEN_ORIGIN. It is intermittent (it depends on whether the jar holds the
cookie that launch), and security.csrf.trustedOrigins cannot fix it: the trust
list is only consulted for an Origin that was actually received, and a missing
one is rejected outright.
createLunoraClient closes this by sending credentials: "omit" on every
request. If you pass your own fetch, wrap it in withoutAmbientCookies (or set
credentials: "omit" yourself) — otherwise you inherit the bug.
API
createLunoraClient(options) accepts everything on LunoraClientOptions plus
storage (an AsyncStorage-shaped store, wired to the offline queue) and
getAuthHeaders (() => Record<string, string> | undefined, a generic
custom-header escape hatch; prefer a bearer token for better-auth sessions). An
explicit persistence, fetch, or WebSocket takes precedence.
@lunora/react-native/auth exports expoBearerToken(authClient) (async) and re-exports
expoClient, setupExpoFocusManager, and setupExpoOnlineManager from
@better-auth/expo/client.