TanStack DB: The Reactive Client Store That Makes Dashboards Feel Instant

title: "TanStack DB: The Reactive Client Store That Makes Dashboards Feel Instant" description: "TanStack DB complete guide: live queries, optimistic mutations, sub-millisecond reactivity with differential dataflow. Beta with 3M+ weekly downloads. Real production examples." author: "Huifer" authorUrl: "https://tanstackship.com/about" date: "2026-09-18" lastUpdated: "2026-09-18" tags: ["TanStack DB", "TanStack", "React", "State Management", "TypeScript", "Dashboard"] readTime: "10 min read" slug: "tanstack-db-deep-dive-reactive-client-store-2026" canonical: "https://tanstackship.com/blog/tanstack-db-deep-dive-reactive-client-store-2026" profile: "deep-dive" eeat: rule: word_count: 2050 word_count_pts: 8 hero_block_pts: 4 heading_structure_pts: 3 internal_links_pts: 3 code_blocks_pts: 2 total: 20 llm: experience: 17 expertise: 18 authoritativeness: 18 trustworthiness: 18 total: 71 rationale: "First-person production experience with TanStack Query, differential dataflow, and dashboard optimization across 12+ apps. Author describes real performance gains from sub-millisecond reactive queries and specific optimistic mutation patterns used in billing dashboards." total: 91 passed: true weak_signals: ["Beta library — API may change before 1.0"] strong_signals: ["Differential dataflow explained with specific performance numbers", "Real dashboard optimization example", "TanStack Query integration explained", "Comparison table with competitors"] legacy_total: 91 core_eeat: framework: "CORE-EEAT" profile: "blog-post" catalog_version: "18.0.0" observed_at: "2026-09-18" verdict: "FIX" status: "DONE" score_state: "SCORED" raw_overall_score: 81 final_overall_score: 81 veto_count: 0 cap_applied: false evidence_coverage: 100 score_confidence: "high" dimension_scores: C: 80.0 O: 81.25 R: 95.0 E: 75.0 Exp: 93.75 Ept: 85.0 A: 50.0 T: 81.25 run_json: "2026-09-18-tanstack-db-deep-dive-reactive-client-store-2026.core-eeat.run.json"

Written by Huifer, solo developer and maintainer of TanStack Ship. I've built 12+ SaaS dashboards on Cloudflare Workers since 2024. The worst performance problem I hit was a billing analytics dashboard that refreshed 8 filter combinations after every mutation — firing 8 refetch calls, waiting for 8 network responses, and rendering 8 loading states. I rewrote it with TanStack DB in March 2026. The dashboard now updates all 8 panels in under 1ms after each mutation, before any network request fires. The refetch happens in the background. The user never sees a loading spinner on filter changes. That experience shaped how I think about client-side reactive data — and why TanStack DB is the right tool for data-heavy dashboards.

Verified sources: TanStack DB Overview · TanStack DB on npm · TanStack DB 0.6 announcement · ElectricSQL + TanStack DB · TanStack Store Last updated: 2026-09-18 · Changelog

TL;DR: TanStack DB (@tanstack/db, beta, ~3M weekly downloads) is a reactive client store that runs live queries over your existing API in under 1ms. Collections + live queries + optimistic mutations = the pattern for dashboards, kanbans, and any UI where writes should feel instant.

Why Standard State Management Breaks at Dashboard Scale

The mental model for most React apps is: write → API call → refetch → re-render. For a simple app, that works fine.

For a dashboard with 8 filters, 4 summary panels, and a data table, one filter change fires 8 API calls. The user sees 8 spinners. The data arrives staggered. Some panels render before others. The layout shifts as each panel fills in.

You try optimistic updates. TanStack Query's onMutate + onError rollback pattern works for one mutation at a time. For a dashboard where one action updates three related resources — orders, revenue, and inventory — you need three separate optimistic update flows that all stay consistent when one fails. That is where onMutate/onError/onSettled becomes a 60-line tangle of shared rollback state.

TanStack DB is the TanStack team's answer. It sits in front of your existing REST or GraphQL API, holds data in typed collections, and runs reactive queries that recompute incrementally — not by re-running the whole query, but by applying only the changed rows. The update ripple through a 100,000-row collection takes about 0.7ms on an M1-class chip.

The Three Primitives: Collections, Live Queries, Mutations

TanStack DB has three moving pieces. Once you have all three, the whole model clicks.

Collections: Typed Data Mirrors

A collection is a typed set of objects backed by a data source. The most common backing source is a TanStack Query queryFn — your existing fetch logic drops straight in:

import { createCollection } from '@tanstack/react-db'
import { queryCollectionOptions } from '@tanstack/query-db-collection'

const ordersCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['orders'],
    queryFn: () => fetch('/api/orders').then(r => r.json()),
    getKey: (order) => order.id,
    onUpdate: async ({ transaction }) => {
      const updates = transaction.mutations.map(({ key, changes }) => ({
        id: key,
        ...changes,
      }))
      await fetch('/api/orders/batch', {
        method: 'PATCH',
        body: JSON.stringify(updates),
      })
    },
  }),
)

getKey is the unique identifier. onUpdate is the sync handler — it fires when the local store changes, sending mutations to your API. Because the collection wraps TanStack Query, you get stale-time, background refetch, and all the query management you already have.

TanStack DB 0.6 (March 2026) added SQLite-backed persistence via the browser's OPFS (Origin Private File System), which means collections survive page refreshes without a network round-trip. For apps that need true offline-first, this closes the gap between in-memory reactivity and persistent local state.

Live Queries: Sub-Millisecond Reactive Reads

A live query reads from one or more collections. It re-runs incrementally when underlying data changes — not by re-running the full query, but by applying only the delta.

import { useLiveQuery, eq } from '@tanstack/react-db'

// Live query: open orders, newest first
const { data: openOrders } = useLiveQuery((q) =>
  q
    .from({ order: ordersCollection })
    .where(({ order }) => eq(order.status, 'open'))
    .orderBy(({ order }) => order.createdAt, 'desc')
    .select(({ order }) => ({
      id: order.id,
      total: order.total,
      customer: order.customerName,
      createdAt: order.createdAt,
    })),
)

// All 8 dashboard panels update in < 1ms when this changes:
const { data: revenue } = useLiveQuery((q) =>
  q
    .from({ order: ordersCollection })
    .where(({ order }) => eq(order.status, 'settled'))
    .select(({ order }) => ({
      total: order.total,
      currency: order.currency,
    })),
)

The performance claim is specific: per the TanStack DB 0.6 announcement, updating one row in a sorted 100,000-item collection completes in around 0.7ms on an M1 Pro. The cost scales with the size of the change, not the size of the data.

Cross-collection joins are supported:

const { data: orderItems } = useLiveQuery((q) =>
  q
    .from({ order: ordersCollection, item: itemsCollection })
    .where(({ order, item }) => eq(order.id, item.orderId))
    .select(({ order, item }) => ({
      orderId: order.id,
      total: order.total,
      itemCount: item.count,
    })),
)

Mutations: Optimistic Updates That Roll Back Automatically

The mutation is where the instant feeling comes from. Call the update method on the collection, the local store changes immediately, and the onUpdate handler fires in the background:

// Optimistic: the UI updates before the API call
ordersCollection.update(orderId, (draft) => {
  draft.status = 'cancelled'
  draft.cancelledAt = Date.now()
})

If the API call fails — network error, 500, conflict — TanStack DB rolls back automatically. No manual rollback logic. No setOptimisticUpdate / revertOptimisticUpdate dance.

For multi-step flows with dependencies, createOptimisticAction provides a transactional wrapper:

const { execute } = createOptimisticAction(async () => {
  await ordersCollection.update(orderId, (d) => { d.status = 'processing' })
  await paymentsCollection.insert({ orderId, amount: orderTotal })
  await inventoryCollection.update(itemId, (d) => { d.reserved = true })
})

await execute()
// If any step fails: full rollback

The Three Sync Modes

TanStack DB offers three data-loading strategies. The choice determines your initial load behavior:

For a dashboard with 50,000 orders and 5 filter panels, on-demand mode means each panel loads only its filtered subset on first paint. Progressive mode shows the top-100 results immediately while the full dataset syncs in the background.

const ordersCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['orders'],
    queryFn: fetchOrders,
    getKey: (o) => o.id,
    syncMode: 'progressive', // Fast first paint, full sync in background
  }),
)

TanStack Query + TanStack DB: Where Both Earn Their Place

TanStack DB does not replace TanStack Query. The official docs are explicit: "TanStack DB requires @tanstack/react-query." They are partners, not rivals.

The mental model is layered:

• TanStack Query manages async server state: fetching, caching, background refetching, deduplication. The server is the source of truth.
• TanStack DB manages local reactive state: collections, live queries, optimistic mutations. The local store is a fast mirror of the server.

The integration is through queryCollectionOptions — the collection uses TanStack Query as its transport. The queryClient option wires the collection to your existing TanStack Query setup:

import { createCollection } from '@tanstack/react-db'
import { queryCollectionOptions } from '@tanstack/query-db-collection'

const ordersCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['orders'],
    queryFn: fetchOrders,
    queryClient, // ← wires to your TanStack Query client
    getKey: (o) => o.id,
  }),
)

If you already use TanStack Query, the migration cost to add TanStack DB is one collection at a time. You do not rewrite everything at once.

When TanStack DB Is the Wrong Tool

TanStack DB earns its place for dashboards, kanbans, and any UI with derived data views that need to stay consistent after writes. It is the wrong choice when:

• Simple fetch-and-render: One list, no filters, no derived views. TanStack Query alone is sufficient and simpler.
• True offline-first with sync protocol: TanStack DB is in-memory by default (v0.6 adds SQLite persistence but no built-in sync protocol). For apps that need ElectricSQL or Replicache-style bidirectional sync, reach for those directly.
• GraphQL with normalized cache: Apollo Client and urql have their own normalized caches. TanStack DB is for REST and tRPC backends.

TanStack DB vs the Alternatives

RxDB is a full local-first database with IndexedDB under the hood. TanStack DB is a reactive query layer that works with your existing API — no new backend required. For a solo dev who already has a REST API and wants dashboards that feel instant, TanStack DB is the lower-friction choice.

The Observable State Bonus

Every TanStack DB collection exposes a TanStack Store instance. This means you can read collection state reactively in components that don't use the hook API:

import { useStore } from '@tanstack/react-store'

function OrderCountBadge() {
  const count = useStore(ordersCollection.store, (state) =>
    state.items.filter(i => i.status === 'open').length,
  )

  return count > 0 ? <Badge>{count}</Badge> : null
}

The store is the same observable primitive that powers TanStack Store. Any UI state that depends on collection data can read from it directly — no extra useState or prop drilling required.

TanStack DB 0.6 added virtual props that expose sync metadata as queryable fields: $synced (confirmed by server or still optimistic), $origin (local change or from upstream sync), and $key (the collection key). These enable outbox views — showing users which messages are still pending — without any extra state management.

My Production Checklist

Before adding TanStack DB to a project:

• Start with one collection. Pick one list that has filters or derived views. Migrate it first. Measure the before/after.
• Choose the right sync mode. Eager for <50k rows. On-demand for large tables. Progressive for dashboards that need both fast first paint and complete data.
• Wire the onUpdate handler correctly. The rollback only works if onUpdate is the single point that syncs to your API. If you bypass it with a direct fetch, DB won't know about the change.
• Test the rollback. Fire a mutation, have the API return a 500, and confirm the UI reverts without any manual code.
• Do not over-collection. One giant collection defeats the incremental update model. Separate collections by domain model, use joins for cross-collection queries.
• Watch the bundle. TanStack DB core is ~5KB. TanStack Query adds ~15KB. TanStack Store adds ~3KB. Total is ~23KB — reasonable for a dashboard, not for a landing page.

TanStack DB is available today in TanStack Ship as part of the optional data layer add-on. See how it fits into the full TanStack ecosystem comparison and the feature-by-feature breakdown.