offline

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 { safeRandomUUID } from '@tanstack/db'
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, }) }, }, })

// Wait for initialization (storage probe, leader election, outbox replay) await executor.waitForInit()

## Core API

### createOfflineTransaction

```ts
const tx = executor.createOfflineTransaction({
  mutationFnName: 'createTodo',
})

// Mutations run inside tx.mutate() — uses ambient transaction context
tx.mutate(() => {
  todoCollection.insert({ id: safeRandomUUID(), 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: safeRandomUUID(),
      text: variables.text,
    })
  },
})

// Call it
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

1. Mutation applied optimistically to collection (instant UI update)
2. Transaction serialized and persisted to storage (outbox)
3. Leader tab picks up transaction and executes mutationFn
4. On success: removed from outbox, optimistic state resolved
5. On failure: retried with exponential backoff
6. 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 // true only if leader AND storage available

Storage degradation

The executor probes storage availability on startup:

const executor = startOfflineExecutor({
  // ...
  onStorageFailure: (diagnostic) => {
    // diagnostic.code: 'STORAGE_BLOCKED' | 'QUOTA_EXCEEDED' | 'UNKNOWN_ERROR'
    // diagnostic.mode: 'online-only'
    console.warn(diagnostic.message)
  },
})

executor.mode // 'offline' | 'online-only'
executor.storageDiagnostic // Full diagnostic info

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> // Collections for optimistic state restoration
  mutationFns: Record<string, OfflineMutationFn> // Named mutation functions
  storage?: StorageAdapter // Custom storage (default: auto-detect)
  maxConcurrency?: number // Parallel execution limit
  jitter?: boolean // Add jitter to retry delays
  shouldRetry?: (error: Error, retryCount: number) => boolean | undefined // Override retry decision
  beforeRetry?: (txs) => txs // Transform/filter before retry
  onUnknownMutationFn?: (name, tx) => void // Handle orphaned transactions
  onLeadershipChange?: (isLeader) => void // Leadership state callback
  onStorageFailure?: (diagnostic) => void // Storage probe failure callback
  leaderElection?: LeaderElection // Custom leader election
  onlineDetector?: OnlineDetector // Custom connectivity detection
}

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 it for failures known to be permanent under the server contract, such as validation errors or a 409 that means an unrecoverable duplicate. A recoverable 401 can instead reach shouldRetry.

Retry decisions

Set shouldRetry to override the default decision for a named mutation function error. The hook receives the named mutation function's Error and retry count (0 on the first failure). The same Error instance is passed through; a non-Error rejection is converted to an Error and may lose custom fields. Return true to retry, false to stop, or undefined to use the default decision. For example, return true for a recoverable 401 and undefined otherwise. NonRetriableError always stops without calling the hook. The default backoff and configured jitter still determine retry timing. The hook is synchronous and shared by all named mutation functions. An async hook returns a Promise, which fails its outbox row. Put function-specific context on the thrown error when retry rules differ between functions. If the hook throws or returns another value, the executor records a terminal rejection for that row, removes it from the outbox, and rejects its waiting promises with the hook failure. Other queued rows continue after the failed row's deletion is acknowledged. New commits may join the queue during cleanup, but cannot run ahead of that deletion. A fresh executor does not replay the failed row. The named mutation function error is logged; the hook failure is the caller-facing and stored error. Stored errors retain name, message, and stack, but a restart does not restore an arbitrary error subclass or its custom fields. If marker storage or deletion fails, the caller still receives the hook error while the executor stops with the storage error and retains queued work. A saved terminal marker skips the named mutation function after restart; an unmarked row can replay. To decide from an HTTP status, throw an error carrying response.status in the named mutation function and inspect its numeric status in shouldRetry.

class HttpError extends Error {
  constructor(readonly status: number) {
    super(`HTTP ${status}`)
    this.name = 'HttpError'
  }
}

function throwOnHttpFailure(response: Response): void {
  if (!response.ok) throw new HttpError(response.status)
}

const retryOnRecoverable401 = (error: Error): boolean | undefined =>
  error instanceof HttpError && error.status === 401 ? true : undefined

Call throwOnHttpFailure(response) in the named mutation function and pass shouldRetry: retryOnRecoverable401 in the executor config.

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'

// Uses ReactNativeOnlineDetector automatically
// Uses AsyncStorage-compatible storage
const executor = startOfflineExecutor({ ... })

Outbox Management

// Inspect pending transactions
const pending = await executor.peekOutbox()

// Get counts
executor.getPendingCount() // Queued transactions
executor.getRunningCount() // Currently executing

// Clear all pending transactions
await executor.clearOutbox()

// Cleanup
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:

class HttpError extends Error {
  constructor(readonly status: number) {
    super(`HTTP ${status}`)
    this.name = 'HttpError'
  }
}

mutationFns: {
  createTodo: async ({ transaction }) => {
    const res = await fetch('/api/todos', { ... })
    if (res.status === 422) {
      throw new NonRetriableError('Invalid todo')
    }
    if (res.status === 409) {
      throw new NonRetriableError('Duplicate detected')
    }
    // This todo API also treats these responses as permanent.
    if ([404, 405, 410].includes(res.status)) {
      throw new NonRetriableError(`Todo endpoint rejected: ${res.status}`)
    }
    if (!res.ok) throw new HttpError(res.status)
  },
}

Classify failures according to whether the app can recover. The default policy stops when an error message contains 400, 401, 403, or 422; it can retry other errors indefinitely. This example marks 404, 405, and 410 as permanent for the todo API while leaving 408 and 429 available for retry. Use shouldRetry when a 401 can recover after credentials refresh, and use NonRetriableError for known permanent failures.

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.