TanStack DB

TanStack DB is a reactive client-side data store designed for high-performance data management. It provides normalized collections, sub-millisecond live queries using differential dataflow (d2ts), and instant optimistic mutations with automatic rollback capabilities.

It is designed to work with various data sources, including:

• REST APIs (via TanStack Query)
• Sync engines (e.g., ElectricSQL, PowerSync, RxDB, TrailBase)
• Local storage

It features framework adapters for React, Vue, Svelte, Solid, and Angular.

The Offline Transactions example demonstrates several key patterns for building resilient, offline-capable applications using @tanstack/offline-transactions:

• Outbox pattern: Mutations are persisted to local storage before attempting to sync with the server.
• Automatic retry: Failed operations automatically retry using exponential backoff once connectivity is restored.
• Optimistic updates: The UI updates immediately to reflect changes while mutations are processed in the background.
• Multi-tab coordination: Uses leader election to ensure that only one browser tab manages the offline storage at a time.
• Collection-level persistence: When using the wa-sqlite route, data is stored in a real SQLite database in the browser via OPFS, allowing data to survive page reloads even without server synchronization.

The @tanstack/db-sqlite-persistence-core package provides shared SQLite persistence primitives for TanStack DB. It includes generic persisted collection wrapper utilities, shared persistence/coordinator protocol types, the SQLite core persistence adapter, validation/storage key helpers, and shared error types.

Important: This package does not include a concrete SQLite engine binding. To use it, you must provide a runtime SQLiteDriver implementation, typically obtained from a runtime-specific wrapper package.

The @tanstack/react-db package provides React hooks for interacting with TanStack DB collections in a reactive, live manner. Key hooks include:

• useLiveQuery: For subscribing to a collection or query and receiving real-time updates.
• useLiveInfiniteQuery: For handling infinite scrolling/pagination with live updates.
• useLiveSuspenseQuery: For using React Suspense to handle loading states during live queries.
• useLiveQueryEffect: For running side effects when query results change.
• usePacedMutations: For managing mutations with pacing/throttling logic.

TanStack DB uses an optimistic mutation pattern to provide a highly responsive user experience. The lifecycle follows these steps:

1. Optimistic state applied: Local changes are applied immediately to the collection.
2. Handler invoked: The appropriate handler (onInsert, onUpdate, onDelete, or a custom mutationFn) is called to persist the change.
3. Backend persistence: The handler sends the data to your backend.
4. Sync back: The handler ensures the server writes have synced back to the collection.
5. Optimistic state dropped: Once synced, the optimistic state is replaced by the confirmed server state.

If the handler throws an error during persistence, the optimistic state is automatically rolled back.