Getting Started with TanStack DB for Reactive UIs

Building reactive UIs shouldn’t require choosing between performance and simplicity. Yet every state update in modern JavaScript applications triggers cascading re-renders, complex memoization, and boilerplate-heavy optimistic updates. TanStack DB changes this equation entirely.

This article introduces TanStack DB—a client-side database layer that extends TanStack Query with collections, live queries, and differential dataflow for sub-millisecond updates. You’ll learn how it simplifies state management compared to Redux or manual caching, and how to incrementally adopt it in your existing projects.

Note: TanStack DB is currently in beta (as of late 2025). While APIs may evolve, it’s stable enough for exploration and incremental adoption in non-critical features.

What Is TanStack DB?

TanStack DB is a reactive client store that builds on top of TanStack Query. While TanStack Query excels at fetching and caching server state, it treats each query result as an isolated cache entry. TanStack DB adds the missing relational layer—enabling joins, filters, and reactive updates across your entire data graph.

The magic lies in differential dataflow, a technique that only recomputes the parts of queries that actually changed. This means updating one row in a 100,000-item collection takes just 0.7ms on an M1 Pro—fast enough to eliminate UI jank entirely.

Core Concepts: Collections, Live Queries, and Optimistic Mutations

Collections: Your Data Foundation

Collections are typed sets of objects that can be populated from any source—REST APIs, GraphQL, or sync engines like ElectricSQL. They wrap your existing useQuery calls:

const todoCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => api.todos.getAll(),
    getKey: (item) => item.id,
    schema: todoSchema
  })
)

This looks familiar because it builds on TanStack Query’s patterns. The difference? Collections normalize your data and enable reactive queries across relationships.

Live Queries: Reactive Without the Boilerplate

Live queries automatically update when underlying data changes—no manual cache invalidation, no useMemo chains:

const { data: activeTodos } = useLiveQuery((query) =>
  query
    .from({ todos: todoCollection })
    .where(({ todos }) => eq(todos.completed, false))
)

When any todo’s status changes, this query updates in under 1ms. The differential dataflow engine ensures only affected rows are recomputed, not the entire dataset.

Optimistic Mutations: Instant UI Updates

TanStack DB handles optimistic updates automatically, with built-in rollback on failure:

// Before: Manual optimistic updates with TanStack Query
const mutation = useMutation({
  mutationFn: createTodo,
  onMutate: async (newTodo) => {
    // 20+ lines of boilerplate...
  }
})

// After: TanStack DB
todoCollection.insert({
  id: uuid(),
  text: 'Ship faster',
  completed: false
})

The mutation appears instantly in your UI and rolls back automatically if the server rejects it. No boilerplate, no manual state management.

Why Differential Dataflow Changes Everything

Traditional state management forces a trade-off: either make many API calls (slow network) or filter large datasets client-side (slow rendering). Differential dataflow enables a third option: load normalized data once, then perform lightning-fast incremental joins in the browser.

Companies like Linear and Figma achieve their instant UIs through custom-built differential update systems. TanStack DB democratizes this approach, making sub-millisecond reactivity accessible to any JavaScript application.

Local-First Sync with ElectricSQL

While TanStack DB works great with REST and GraphQL, it truly shines when paired with sync engines. ElectricSQL, for example, uses Postgres logical replication to stream changes directly to clients:

const todoCollection = createCollection(
  electricCollectionOptions({
    shapeOptions: {
      url: 'http://localhost:3003/v1/shape',
      params: { table: 'todos' }
    },
    getKey: (item) => item.id
  })
)

Now any change to your Postgres database instantly updates all connected clients—no WebSocket plumbing, no manual broadcasting. This local-first sync pattern eliminates network latency from user interactions entirely.

Incremental Adoption Path

TanStack DB layers on top of your existing TanStack Query setup. Start with one collection, keep your current API calls, and migrate incrementally:

1. Wrap an existing query in a collection
2. Replace filtered arrays with live queries
3. Simplify mutations with automatic optimistic updates
4. (Optional) Add real-time sync with ElectricSQL

Each step improves performance and reduces complexity. No big-bang rewrites required.

Conclusion

TanStack DB brings differential dataflow to JavaScript, enabling reactive UIs that update in microseconds rather than milliseconds. By extending TanStack Query with collections and live queries, it eliminates the traditional trade-offs between network efficiency and rendering performance.

While still in beta, TanStack DB is ready for exploration and incremental adoption. Start with a single collection in a non-critical feature and experience the difference sub-millisecond updates make to your application’s feel. Your users—and your codebase—will thank you.

FAQs

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.