| name | offline |
| description | Offline transaction support for TanStack DB. OfflineExecutor orchestrates persistent outbox (IndexedDB/localStorage), leader election (WebLocks/ BroadcastChannel), retry with backoff, and connectivity detection. createOfflineTransaction/createOfflineAction wrap TanStack DB primitives with offline persistence. Idempotency keys for at-least-once delivery. Graceful degradation to online-only mode when storage unavailable. React Native support via separate entry point.
|
| type | composition |
| library | db |
| library_version | 0.6.0 |
| requires | ["db-core","db-core/mutations-optimistic"] |
| sources | ["TanStack/db:packages/offline-transactions/src/OfflineExecutor.ts","TanStack/db:packages/offline-transactions/src/types.ts","TanStack/db:packages/offline-transactions/src/index.ts"] |
This skill builds on db-core and mutations-optimistic. Read those first.
TanStack DB — Offline Transactions
Setup
import {
startOfflineExecutor,
IndexedDBAdapter,
} from '@tanstack/offline-transactions'
import { todoCollection } from './collections'
const executor = startOfflineExecutor({
collections: { todos: todoCollection },
mutationFns: {
createTodo: async ({ transaction, idempotencyKey }) => {
const mutation = transaction.mutations[0]
await api.todos.create({
...mutation.modified,
idempotencyKey,
})
},
updateTodo: async ({ transaction, idempotencyKey }) => {
const mutation = transaction.mutations[0]
await api.todos.update(mutation.key, {
...mutation.changes,
idempotencyKey,
})
},
},
})
await executor.waitForInit()
Core API
createOfflineTransaction
const tx = executor.createOfflineTransaction({
mutationFnName: 'createTodo',
})
tx.mutate(() => {
todoCollection.insert({ id: crypto.randomUUID(), text: 'New todo' })
})
tx.commit()
If the executor is not the leader tab, falls back to createTransaction directly (no offline persistence).
createOfflineAction
const addTodo = executor.createOfflineAction({
mutationFnName: 'createTodo',
onMutate: (variables) => {
todoCollection.insert({
id: crypto.randomUUID(),
text: variables.text,
})
},
})
addTodo({ text: 'Buy milk' })
If the executor is not the leader tab, falls back to createOptimisticAction directly.
Architecture
Components
| Component | Purpose | Default |
|---|
| Storage | Persist transactions to survive page reload | IndexedDB → localStorage fallback |
| OutboxManager | FIFO queue of pending transactions | Automatic |
| KeyScheduler | Serialize transactions touching same keys | Automatic |
| TransactionExecutor | Execute with retry + backoff | Automatic |
| LeaderElection | Only one tab processes the outbox | WebLocks → BroadcastChannel |
| OnlineDetector | Pause/resume on connectivity changes | navigator.onLine + events |
Transaction lifecycle
- Mutation applied optimistically to collection (instant UI update)
- Transaction serialized and persisted to storage (outbox)
- Leader tab picks up transaction and executes
mutationFn
- On success: removed from outbox, optimistic state resolved
- On failure: retried with exponential backoff
- On page reload: outbox replayed, optimistic state restored
Leader election
Only one tab processes the outbox to prevent duplicate execution. Non-leader tabs use regular createTransaction/createOptimisticAction (online-only, no persistence).
const executor = startOfflineExecutor({
onLeadershipChange: (isLeader) => {
console.log(
isLeader
? 'This tab is processing offline transactions'
: 'Another tab is leader',
)
},
})
executor.isOfflineEnabled
Storage degradation
The executor probes storage availability on startup:
const executor = startOfflineExecutor({
onStorageFailure: (diagnostic) => {
console.warn(diagnostic.message)
},
})
executor.mode
executor.storageDiagnostic
When storage is unavailable (private browsing, quota exceeded), the executor operates in online-only mode — mutations work normally but aren't persisted across page reloads.
Configuration
interface OfflineConfig {
collections: Record<string, Collection>
mutationFns: Record<string, OfflineMutationFn>
storage?: StorageAdapter
maxConcurrency?: number
jitter?: boolean
beforeRetry?: (txs) => txs
onUnknownMutationFn?: (name, tx) => void
onLeadershipChange?: (isLeader) => void
onStorageFailure?: (diagnostic) => void
leaderElection?: LeaderElection
onlineDetector?: OnlineDetector
}
Custom storage adapter
interface StorageAdapter {
get: (key: string) => Promise<string | null>
set: (key: string, value: string) => Promise<void>
delete: (key: string) => Promise<void>
keys: () => Promise<Array<string>>
clear: () => Promise<void>
}
Error Handling
NonRetriableError
import { NonRetriableError } from '@tanstack/offline-transactions'
const executor = startOfflineExecutor({
mutationFns: {
createTodo: async ({ transaction, idempotencyKey }) => {
const res = await fetch('/api/todos', { method: 'POST', body: ... })
if (res.status === 409) {
throw new NonRetriableError('Duplicate detected')
}
if (!res.ok) throw new Error('Server error')
},
},
})
Throwing NonRetriableError stops retry and removes the transaction from the outbox. Use for permanent failures (validation errors, conflicts, 4xx responses).
Idempotency keys
Every offline transaction includes an idempotencyKey. Pass it to your API to prevent duplicate execution on retry:
mutationFns: {
createTodo: async ({ transaction, idempotencyKey }) => {
await fetch('/api/todos', {
method: 'POST',
headers: { 'Idempotency-Key': idempotencyKey },
body: JSON.stringify(transaction.mutations[0].modified),
})
},
}
React Native
import {
startOfflineExecutor,
} from '@tanstack/offline-transactions/react-native'
const executor = startOfflineExecutor({ ... })
Outbox Management
const pending = await executor.peekOutbox()
executor.getPendingCount()
executor.getRunningCount()
await executor.clearOutbox()
executor.dispose()
Common Mistakes
CRITICAL Not passing idempotencyKey to the API
Wrong:
mutationFns: {
createTodo: async ({ transaction }) => {
await api.todos.create(transaction.mutations[0].modified)
},
}
Correct:
mutationFns: {
createTodo: async ({ transaction, idempotencyKey }) => {
await api.todos.create({
...transaction.mutations[0].modified,
idempotencyKey,
})
},
}
Offline transactions retry on failure. Without idempotency keys, retries can create duplicate records on the server.
HIGH Not waiting for initialization
Wrong:
const executor = startOfflineExecutor({ ... })
const tx = executor.createOfflineTransaction({ mutationFnName: 'createTodo' })
Correct:
const executor = startOfflineExecutor({ ... })
await executor.waitForInit()
const tx = executor.createOfflineTransaction({ mutationFnName: 'createTodo' })
startOfflineExecutor initializes asynchronously (probes storage, requests leadership, replays outbox). Creating transactions before initialization completes may miss the leader election result and use the wrong code path.
HIGH Missing collection in collections map
Wrong:
const executor = startOfflineExecutor({
collections: {},
mutationFns: { createTodo: ... },
})
Correct:
const executor = startOfflineExecutor({
collections: { todos: todoCollection },
mutationFns: { createTodo: ... },
})
The collections map is used to restore optimistic state from the outbox on page reload. Without it, previously pending mutations won't show their optimistic state while being replayed.
MEDIUM Not handling NonRetriableError for permanent failures
Wrong:
mutationFns: {
createTodo: async ({ transaction }) => {
const res = await fetch('/api/todos', { ... })
if (!res.ok) throw new Error('Failed')
},
}
Correct:
mutationFns: {
createTodo: async ({ transaction }) => {
const res = await fetch('/api/todos', { ... })
if (res.status >= 400 && res.status < 500) {
throw new NonRetriableError(`Client error: ${res.status}`)
}
if (!res.ok) throw new Error('Server error')
},
}
Without distinguishing retriable from permanent errors, 4xx responses (validation, auth, not found) will retry forever until max retries, wasting resources and filling logs.
See also: db-core/mutations-optimistic/SKILL.md — for the underlying mutation primitives.
See also: db-core/collection-setup/SKILL.md — for setting up collections used with offline transactions.