tanstack-db

TanStack DB

Overview

TanStack DB is a reactive client store built on differential dataflow that extends TanStack Query with collections, live queries, and optimistic mutations. It normalizes data into typed collections, enables sub-millisecond cross-collection queries, and provides instant optimistic updates with automatic rollback on failure.

When to use: Reactive UIs needing local-first data, cross-collection joins with live updates, optimistic mutations with automatic sync, real-time sync via ElectricSQL or other backends, apps that outgrow TanStack Query's per-query caching model.

When NOT to use: Simple fetch-and-display (TanStack Query alone suffices), server-components-only apps, purely synchronous local state (useState/Zustand), GraphQL with normalized caching (Apollo/urql).

TanStack DB is currently in beta. APIs may change between releases.

Quick Reference

Pattern	API	Key Points
Create collection	createCollection(queryCollectionOptions({...}))	Define typed set of objects with getKey
Live query (React)	useLiveQuery((q) => q.from({...}).where(...))	Auto-updates when underlying data changes
Filter	.where(({ t }) => eq(t.field, value))	Supports eq, gt, lt, like, and, or, not
Select fields	.select(({ t }) => ({ id: t.id, name: t.name }))	Project specific fields from collections
Order results	.orderBy(({ t }) => t.field, 'asc')	Sort ascending or descending
Join collections	.join({ b: collB }, ({ a, b }) => eq(...), 'inner')	Cross-collection joins with type safety
Group and aggregate	.groupBy(...).select(({ t }) => ({ count: count(t.id) }))	Supports count, sum, avg, min, max
Insert	collection.insert({ ...data })	Optimistic insert, syncs via onInsert handler
Update	collection.update(key, (draft) => { ... })	Immer-style draft mutation, syncs via onUpdate
Delete	collection.delete(key)	Optimistic delete, syncs via onDelete handler
Electric sync	electricCollectionOptions({ shapeOptions: {...} })	Real-time Postgres sync via ElectricSQL
Live query coll.	liveQueryCollectionOptions({ query })	Derived collection from live query definition
Local storage	localStorageCollectionOptions({...})	Persistent local data, syncs across tabs

Sync Modes (v0.5+)

Mode	Behavior	Use Case
Eager (default)	Loads all records on collection init	Small datasets (< 1k rows)
On-demand	Loads only what queries request (predicate pushdown)	Large datasets, selective loading
Progressive	Fast first paint, full dataset syncs in background	Best of both, scales to 100k+

Common Mistakes

Mistake	Correct Pattern
Using TanStack Query directly for local state	Use collections with live queries for reactive local data
Forgetting getKey in collection config	Always provide getKey to identify items uniquely
Not providing persistence handlers	Define onInsert/onUpdate/onDelete to sync with server
Using useQuery instead of useLiveQuery	useLiveQuery provides reactive cross-collection queries
Creating collections inside components	Define collections at module scope, outside components
Importing from @tanstack/db in React apps	Import from @tanstack/react-db (re-exports core)
Expecting automatic server sync without config	Collections require explicit persistence handlers for sync
Not installing collection type package	Install @tanstack/query-db-collection for REST API usage

Delegation

If the tanstack-query skill is available, delegate TanStack Query-specific patterns (query keys, cache invalidation, SSR) to it. Otherwise, recommend: npx skills add oakoss/agent-skills --skill tanstack-query If the electricsql skill is available, delegate ElectricSQL setup, shapes, auth proxy, and write patterns to it. Otherwise, recommend: pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y If the local-first skill is available, delegate architecture decisions, sync engine comparison, and conflict resolution to it. Otherwise, recommend: pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y

• Query pattern discovery: Use Explore agent
• Architecture review: Use Task agent

References

• Setup, installation, and collection configuration
• Live queries, filtering, joins, and aggregations
• Optimistic mutations, persistence handlers, and sync patterns
• ElectricSQL integration, electric collections, and txid patterns
• Error class hierarchy, transaction states, and rollback patterns
• Local-only and localStorage collections with cross-tab sync
• Cross-collection transactions, joins, batching, and lifecycle