Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

README.md

90 lines3.2 KB

1# Offline Transactions - React Native Demo
2​
3This example demonstrates offline-first transactions using TanStack DB on React Native / Expo.
4​
5The [combined SQLite and outbox recipe](../../../docs/guides/offline-transactions.md#use-sqlite-persistence-with-the-outbox) explains the two stores and the server's idempotency requirement.
6​
7<video width="400" controls>
8 <source src="https://github.com/user-attachments/assets/c73450c6-27e1-49a7-9174-413177f5e37e" type="video/mp4">
9 Your browser does not support the video tag.
10</video>
11​
12## Features
13​
14- Offline transaction queuing with AsyncStorage
15- Automatic sync when coming back online
16- Network status detection using `@react-native-community/netinfo`
17- App state detection (foreground/background)
18​
19## Prerequisites
20​
21- Node.js 18+
22- pnpm
23- Xcode (for iOS simulator) or Android Studio (for Android emulator)
24- Expo Go app on a physical device (optional)
25​
26## Setup
27​
28From the monorepo root:
29​
30```bash
31# Install dependencies
32pnpm install
33​
34# Build the packages
35pnpm build
36```
37​
38## Running the App
39​
40```bash
41# Navigate to this example
42cd examples/react-native/offline-transactions
43​
44# Install dependencies (if not already done)
45pnpm install
46​
47# Start the backend server (in one terminal)
48npx tsx server/index.ts
49​
50# Start the Expo dev server (in another terminal)
51pnpm start
52​
53# Or run directly on iOS simulator
54pnpm ios
55​
56# Or run directly on Android emulator
57pnpm android
58```
59​
60The backend server runs on port 3001 and is shared by all emulators/devices. This allows you to test real syncing between multiple devices.
61​
62## Testing Sync Between Devices
63​
641. **Start the server** with `pnpm server`
652. **Run the app on two emulators** (e.g., iOS + Android, or two Android emulators)
663. **Add a todo on one device** - It syncs to the server
674. **Pull to refresh on the other device** - You'll see the new todo
68​
69## Testing Offline Mode
70​
711. **Add todos while online** - They sync immediately to the backend server
722. **Enable airplane mode** on your device/simulator
733. **Add more todos** - They're queued locally in AsyncStorage
744. **Disable airplane mode** - Queued transactions sync automatically
75​
76## Architecture
77​
78- **AsyncStorageAdapter**: Implements `StorageAdapter` for React Native using `@react-native-async-storage/async-storage`
79- **ReactNativeOnlineDetector**: Uses `NetInfo` and `AppState` to detect connectivity changes (imported from `@tanstack/offline-transactions/react-native`)
80- **todoCollection**: TanStack DB collection with live queries
81- **Offline actions**: Create, toggle, delete todos with optimistic updates
82​
83## Key Differences from Web
84​
85| Web | React Native |
86| -------------------------------------------- | --------------------------------------------------------- |
87| IndexedDB / localStorage | AsyncStorage |
88| `window.addEventListener('online')` | NetInfo.addEventListener |
89| `document.visibilitychange` | AppState.addEventListener |
90| Import from `@tanstack/offline-transactions` | Import from `@tanstack/offline-transactions/react-native` |