- Home
- Skills
- Mobile Development
- expo-offline-first
Works with the AI Agents you already use
Expo Offline First
Production offline-first patterns for Expo and React Native: SQLite outbox, Idempotency-Key retries, persisted TanStack Query cache and offline UX. Based on a shipping app.
Free
expo-offline-first
Example session with this skill installed
My app loses user posts if they close the app while the connection is flaky. How do I build a durable outbox with SQLite to fix this?
- Read your context and instructions
- Compiled the expo-offline-first
I will implement a durable outbox architecture using expo-sqlite to ensure user posts are persisted to disk before attempting any network requests. This approach includes a state machine to handle retries and idempotency.
Durable Outbox Implementation
SQLite Schema and State Machine
We use a dedicated SQLite database to track the lifecycle of each post. The state moves from pending to sending, then either done or failed based on the server response.
// src/services/outbox/outbox-db.ts
import * as SQLite from 'expo-sqlite';
export type OutboxJob = {
id: string; // UUID for idempotency
type: 'POST_CREATE';
payload: string; // JSON stringified body
state: 'pending' | 'sending' | 'failed';
attempts: number;
last_error?: string;
};
const db = SQLite.openDatabaseSync('outbox.db');
export const initOutbox = () => {
db.execSync(`
CREATE TABLE IF NOT EXISTS outbox (
id TEXT PRIMARY KEY NOT NULL,
type TEXT NOT NULL,
payload TEXT NOT NULL,
state TEXT DEFAULT 'pending',
attempts INTEGER DEFAULT 0,
last_error TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
`);
};
export const enqueuePost = (id: string, data: any) => {
db.runSync(
'INSERT INTO outbox (id, type, payload) VALUES (?, ?, ?)',
[id, 'POST_CREATE', JSON.stringify(data)]
);
};
Outbox Processing Hook
This hook monitors the network status and triggers the processing loop when the device is back online.
// src/hooks/useOutboxProcessor.ts
import { useEffect } from 'react';
import { useIsOnline } from './useIsOnline';
export function useOutboxProcessor() {
const isOnline = useIsOnline();
useEffect(() => {
if (isOnline) {
processNextJob();
}
}, [isOnline]);
async function processNextJob() {
// 1. Pick oldest pending job
// 2. Set state to 'sending'
// 3. POST to /posts with Idempotency-Key: job.id
// 4. On success: delete row
// 5. On failure: update attempts and backoff
}
}
Next steps
- Integrate
Idempotency-Keyheader in your API client to prevent duplicate posts. - Add a
PendingCardUI component to show the user their post is "Waiting for connection". - Configure
expo-file-systemto move any attached images to theDocumentsdirectory before enqueuing.
Connects securely to your tools. The creator never sees your data.
About this skill
Making mobile apps usable in low-connectivity environments requires more than just checking a network status flag. This skill provides a technical architecture for building truly offline-first Expo and React Native applications. It solves the problem of data loss during app kills, duplicate charges due to network timeouts, and jarring UI transitions when a user loses signal.
What it does
- Network Management wires
expo-networkinto TanStack Query to synchronizeonlineManagerandfocusManagerwith the native device state. - Cache Persistence configures
expo-sqliteas a KV-store for the query cache to ensure data is available instantly on cold starts. - Durable Outbox implements a SQLite-backed queue that persists user actions and file uploads to disk before execution.
- Idempotency Logic ensures every queued mutation carries a unique key to prevent double-processing on the server during retries.
- Offline UI Components provides design patterns for non-blocking indicators, pending state cards, and grouped success toasts.
How it works
- Initialize the network managers and SQLite persister in the app root to hydrate the query cache from local storage.
- Queue user actions by writing the request body, file paths, and a unique UUID to the outbox database.
- Synchronize the outbox using a state machine that handles exponential backoff, jitter, and manual retries for failed jobs.
- Guard sensitive operations like payments and authentication to ensure they only execute when a verified connection is present.
Frameworks & tools
Built for Expo SDK 54+ and React Native. It utilizes expo-sqlite, expo-network, expo-file-system, and TanStack Query (React Query).
Why this beats prompting it yourself
Generic AI prompts often suggest fragile solutions like storing queues in AsyncStorage or React state, which lose data if the app crashes. This skill enforces a durable SQLite state machine and idempotency patterns that prevent data corruption and duplicate API side effects.
Use cases
- Queueing form submissions or social posts while the user is in a tunnel or on a plane.
- Preventing double-billing in payment flows when the connection drops mid-request.
- Building field-service apps where workers must perform CRUD operations in remote areas.
- Reducing "empty state" flickering by rendering cached profile and list data immediately on launch.
Known limitations
Does not support multi-device conflict resolution or real-time collaboration. Not suitable for OAuth sign-in or native IAP flows which require an active connection.
Requires Expo SDK 54+. Not for multi-device sync or collaborative editing. Native purchases and OAuth cannot be faked offline. Storing large blobs or base64 in SQLite is explicitly avoided.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 18 days ago
- Free with an Agensi account
Requires