Skip to content
DocspackagesDocumentation

@lunora/react-native

React Native / Expo bindings for Lunora — the @lunora/react hooks plus an AsyncStorage-backed client factory and a better-auth Expo bridge.

PackagesReact Native

@lunora/react-native is the React Native / Expo entry to Lunora. It re-exports the whole @lunora/react surface: the hooks are react-dom-free and touch no browser-only global, so useQuery, useMutation, useSubscription, useAuth, useConnectionStatus and the rest run unchanged on native. On top of that it adds the two things a native app needs that a browser gives you for free: an AsyncStorage-backed offline queue, and credentialed requests (the session is a bearer, attached explicitly to every HTTP RPC call and the WebSocket upgrade).

CheckoutButton, CustomerPortalButton, and useCheckout are not part of that surface: they render a DOM <button> and navigate via globalThis.location, so they ship from the browser-only @lunora/react/payment subpath instead of the @lunora/react root — there is nothing to strip out here. Drive purchases through the platform's own purchase flow, or a WebView pointed at the web checkout URL.

useVoiceAgent is re-exported, but its defaults are Web APIs (getUserMedia, Web Audio, WebSocket) — on native, supply your own createMicrophone / createSpeaker implementations.

See the React Native / Expo guide for the task-oriented walkthrough.

The following root component creates a client with AsyncStorage and mounts the provider:

import AsyncStorage from "@react-native-async-storage/async-storage";
import { createLunoraClient, LunoraProvider, useQuery } from "@lunora/react-native";
import { api } from "@/lunora/_generated/api";

const client = createLunoraClient({
    url: process.env.EXPO_PUBLIC_LUNORA_URL!,
    storage: AsyncStorage,
});

const Root = () => (
    <LunoraProvider client={client}>
        <Chat />
    </LunoraProvider>
);

createLunoraClient(options)

A thin wrapper over new LunoraClient(options). Accepts everything on LunoraClientOptions (url, wsUrl, authBasePath, persistenceVersion, …) plus two React-Native conveniences:

  • storage: React Native AsyncStorage (or any getItem/setItem/removeItem store). Wires createAsyncStoragePersistence so the offline mutation queue survives an app restart, and createAsyncStorageQueryCache so query results repaint before the socket reconnects. The browser client auto-probes IndexedDB, which React Native lacks, so without this both stay in memory. Each is opted out of separately — persistence: false disables the queue and leaves the query cache writing to storage; pass queryCache: false for that.
  • getAuthHeaders: () => Record<string, string> | undefined. A generic escape hatch for a custom credential header (an API-gateway key, a proxy token) attached to every HTTP RPC request and the WebSocket upgrade. For better-auth sessions prefer a bearer token (below); a Cookie header here would be rejected by the runtime's CSRF guard on an Origin-less native request.

An explicit persistence, queryCache, fetch, or WebSocket takes precedence over the convenience derived from storage / getAuthHeaders.

Hooks & provider

Re-exported verbatim from @lunora/react: LunoraProvider, useLunora, useQuery, useMutation, useSubscription, useAuth, usePresence, useConnectionStatus, usePaginatedQuery, useInfiniteQuery, useStream, useFlag/useFlags, useRateLimit, the Authenticated / Unauthenticated / AuthLoading gates, and the framework-neutral error discriminators. Mount them inside LunoraProvider exactly as on the web (it creates, or reuses, the TanStack QueryClient they need).

@lunora/react-native/auth

The better-auth Expo bridge. Auth is a bearer token: the session rides the Authorization header on HTTP RPC and, on native, on the WebSocket upgrade — never the URL.

React Native does have a cookie jar — fetch is backed by the platform HTTP stack (NSURLSession / OkHttp) and its shared cookie store — so a Set-Cookie from a better-auth sign-in is kept and re-attached to later requests. That is a problem, not a second credential: the runtime's CSRF guard rejects an unsafe, cookie-bearing request whose Origin is missing or untrusted, and a native request sends no Origin, so every state-changing RPC would 403 for as long as the jar held that cookie. createLunoraClient sends credentials: "omit" on every request so the jar never rides along; a caller supplying its own fetch should wrap it in withoutAmbientCookies.

  • expoBearerToken(authClient): reads the better-auth Expo session token (from getCookie()) for use with client.setAuthToken, which covers HTTP and, on native, the WebSocket upgrade's Authorization header; returns null when signed out. Never pass it to client.setWsToken: that carries the shared LUNORA_WS_BEARER value in the connect frame.
  • expoClient, setupExpoFocusManager, setupExpoOnlineManager: re-exported from @better-auth/expo/client.

The following module creates the better-auth client and the Lunora client, both against the same base URL, and syncs the session token into the Lunora client:

import { createAuthClient } from "better-auth/react";
import { expoClient, expoBearerToken } from "@lunora/react-native/auth";
import * as SecureStore from "expo-secure-store";

export const authClient = createAuthClient({
    baseURL: process.env.EXPO_PUBLIC_LUNORA_URL!,
    plugins: [expoClient({ scheme: "myapp", storage: SecureStore })],
});

export const client = createLunoraClient({
    url: process.env.EXPO_PUBLIC_LUNORA_URL!,
    storage: AsyncStorage,
});

// Sync the token into the client whenever the session changes, in an effect keyed
// on `authClient.useSession()`. `expoBearerToken` is async since better-auth
// 1.7, so guard the write with a cleanup flag — two session changes in quick
// succession leave two reads in flight, and the slower one would otherwise
// reinstate the previous session's token:
useEffect(() => {
    let cancelled = false;

    void (async () => {
        const token = await expoBearerToken(authClient);
        if (cancelled) return;
        client.setAuthToken(token);
    })();

    return () => {
        cancelled = true;
    };
}, [session]);

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 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.

On the server, add better-auth's expo() and bearer() plugins and read the session from the request headers in resolveIdentity (see @lunora/auth).

API

Reference for the native exports of this package. The hooks and provider that it re-exports from @lunora/react are documented on the @lunora/react page.

createLunoraClient

Type: (options: CreateLunoraClientOptions) => LunoraClient

Creates a LunoraClient. The storage option wires the AsyncStorage offline queue and query cache, and getAuthHeaders adds a custom credential header to every HTTP request and the WebSocket upgrade. See createLunoraClient(options) above for the options.

CreateLunoraClientOptions

Type: interface

The options for createLunoraClient. It extends LunoraClientOptions with the storage and getAuthHeaders conveniences.

AuthHeadersFactory

Type: () => Record<string, string> | undefined

Returns the headers that getAuthHeaders attaches to each request.

withoutAmbientCookies

Type: (fetchImpl: typeof fetch) => typeof fetch

Wraps a fetch so that it sends credentials: "omit". Use it when you pass your own fetch to the client, so that cookies in the platform cookie jar are not attached to requests.

expoBearerToken

Type: (authClient: { getCookie: () => Promise<string> | string }) => Promise<string | null>

Imported from @lunora/react-native/auth. Returns the better-auth Expo session token, or null when signed out. Pass the result to client.setAuthToken.