React Native SDK

• AsyncStorage-backed durable replica — the local sync replica survives app kills (via AsyncStorageReplicaPersistence, enabled by default)
• AsyncStorage bridge — auth tokens + client id persist correctly on iOS / Android
• useNetworkStatus hook for offline-aware UI
• Foreground/background lifecycle handling — sync pauses when backgrounded, catches up on resume

​

Install

bun add @pylonsync/sdk @pylonsync/react @pylonsync/react-native
bun add @react-native-async-storage/async-storage @react-native-community/netinfo

​

Configure

import { init } from "@pylonsync/react-native";

// await it before rendering — otherwise the first paint renders against
// an unauthenticated / empty cache.
await init({
  baseUrl: "https://your-app.com",
  appName: "myapp",
});

​

Use the React hooks

import { db, useSession } from "@pylonsync/react-native";

function TodoScreen() {
  const { auth } = useSession(db.sync);
  const { data: todos } = db.useQuery("Todo");
  const { insert, update, remove } = db.useEntity("Todo");

  return (
    <FlatList
      data={todos}
      keyExtractor={t => t.id}
      renderItem={({ item }) => (
        <TodoRow
          todo={item}
          onToggle={() => update(item.id, { done: !item.done })}
          onDelete={() => remove(item.id)}
        />
      )}
    />
  );
}

​

Offline persistence

import { createSyncEngine } from "@pylonsync/sync";
import {
  AsyncStorageReplicaPersistence,
  createAsyncStorageBridge,
} from "@pylonsync/react-native";

const storage = await createAsyncStorageBridge();
const persistence = new AsyncStorageReplicaPersistence("myapp");

const engine = createSyncEngine("https://your-app.com", {
  storage,
  persistence,
});

• The replica snapshot + cursor are persisted to AsyncStorage (durable across cold launches)
• The mutation queue is persisted (offline writes survive app kill)
• App startup hydrates from the persisted replica first, then catches up via pull

​

Network status

import { useNetworkStatus } from "@pylonsync/react-native";

function Header() {
  const { isOnline, connectionType } = useNetworkStatus();
  if (!isOnline) return <OfflineBanner />;
  if (connectionType === "cellular") return <SlowConnectionBanner />;
  return null;
}

​

Foreground / background

• Background → pause WebSocket; mutations still queue locally
• Foreground → reconnect, pull missed changes, drain the queue

​

Higher-level offline store

import { OfflineStore } from "@pylonsync/react-native";

const store = new OfflineStore();

await store.saveEntities("FavoriteRecipes", recipes);
const cached = await store.loadEntities("FavoriteRecipes");

​

Performance

• Use FlatList/SectionList with useQuery results — they re-render fully on every store change, so list virtualization matters.
• Memoize derived data with useMemo to avoid re-computing on every store notify.
• Limit useQuery results — for large entities, use useInfiniteQuery instead so the screen doesn’t render thousands of rows.
• Backgrounded sync uses zero CPU — the engine pauses cleanly.

​

Push notifications

1. On sign-in, register the device token with your Pylon backend (POST /api/fn/registerPushToken).
2. In your function/cron, push when something interesting happens.
3. On notification tap, foreground the app — the sync engine catches up automatically.

​

Tested combinations

• Expo SDK 50+
• React Native 0.74+ (peer-dependency floor)
• New Architecture (Fabric / TurboModules) — works
• Hermes JS engine — works (no Loro CRDT WASM dependency in this package)
• Bare React Native — works after manual native module linking

​

Differences from web React