React Native

@nizhal/react-native wires Nizhal for Expo/React Native: realtime over native WebSockets and HTTP over nitro-fetch.

Install

npm i @nizhal/react-native @nizhal/db-collection \
  react-native-nitro-fetch react-native-nitro-websockets \
  react-native-nitro-text-decoder react-native-nitro-modules
npx expo install @react-native-community/netinfo
cd ios && pod install && cd ..

One-call setup

import { createNizhalNitroClient } from "@nizhal/react-native";

const echo = createNizhalNitroClient({
  server: "https://api.myshop.lk",
  token: session.accessToken,
  bucketsForSyncRule: (rule) => myBuckets(rule),
});

Installs native polyfills (installNizhalNativePolyfills), global fetch via installNitroFetch, and nitroWebSocketSource for realtime with Authorization on the WS upgrade.

À la carte

import {
  installNitroFetch,
  nitroWebSocketSource,
  installNizhalNativePolyfills,
  reactNativeOnlineDetector,
} from "@nizhal/react-native";
import { createNizhalClient, createNizhalMutators, opSqlitePersistence } from "@nizhal/db-collection";

installNizhalNativePolyfills();
installNitroFetch();

const echo = createNizhalClient({
  server: "https://api.myshop.lk",
  subscribeSource: nitroWebSocketSource({ server: "https://api.myshop.lk", token }),
  bucketsForSyncRule,
});

const { mutate } = createNizhalMutators({
  ...,
  onlineDetector: reactNativeOnlineDetector(),
});

Why native transport

RN’s JS WebSocket cannot set upgrade headers — bearer tokens would leak in query strings. NitroWebSocket sends Authorization properly (with ?token= fallback).

Realtime model (RFC-005)

• Local reactivity — TanStack DB useLiveQuery on device
• NetInfo — reactNativeOnlineDetector flushes outbox on reconnect
• WS — optional instant push; missed ping → catch-up pull on reconnect

The cursor pull is authoritative; WS is a hint.

Persistence

nizhalCollectionOptions({
  ...,
  persistence: opSqlitePersistence({ name: "shop", location: "default" }),
});

Verified: apps/op-sqlite-probe — offline write + app restart on iOS simulator.

Exports

nitroWebSocketSource, installNitroFetch, nitroFetch, createNizhalNitroClient, reactNativeOnlineDetector, installNizhalNativePolyfills