TanStack DB

A reactive client store for building super fast apps on sync

TanStack DB extends TanStack Query with collections, live queries and optimistic mutations that keep your UI reactive, consistent and blazing fast 🔥

Enjoy this library? Try the entire TanStack, including TanStack Query, TanStack Store, etc.

🚀 Why TanStack DB?

TanStack DB gives you robust support for real-time sync, live queries and local writes. With no stale data, super fast re-rendering and sub-millisecond cross-collection queries — even for large complex apps.

Built on a TypeScript implementation of differential dataflow (#), TanStack DB gives you:

• 🔥 a blazing fast query engine
  for sub-millisecond live queries — even for complex queries with joins and aggregates
• 🎯 fine-grained reactivity
  to minimize component re-rendering
• 💪 robust transaction primitives
  for easy optimistic mutations with sync and lifecycle support
• 🌟 normalized data
  to keep your backend simple

TanStack DB is backend agnostic and incrementally adoptable:

• plug in any backend: sync engines, REST APIs, GraphQL, polling, custom sources
• builds on TanStack Store, works with and alongside TanStack Query

💥 Usage example

Sync data into collections:

import{createCollection,QueryClient}from"@tanstack/react-db"import{queryCollectionOptions}from"@tanstack/query-db-collection"consttodoCollection=createCollection(queryCollectionOptions({queryKey: ["todos"],queryFn: async()=>fetch("/api/todos"),queryClient: newQueryClient(),getKey: (item)=>item.id,schema: todoSchema,// any standard schema}))

Use live queries in your components:

import{useLiveQuery}from"@tanstack/react-db"import{eq}from"@tanstack/db"constTodos=()=>{const{data: todos}=useLiveQuery((query)=>query.from({todos: todoCollection}).where(({ todos })=>eq(todos.completed,false)))return<Listitems={todos}/>}

Apply mutations with local optimistic state:

// Define collection with persistence handlersconsttodoCollection=createCollection({id: "todos",// ... other configonInsert: async({ transaction })=>{constmodified=transaction.mutations[0].modifiedawaitapi.todos.create(modified)},})// Then use collection operators in your componentsconstAddTodo=()=>{return(<ButtononClick={()=>todoCollection.insert({id: uuid(),text: "🔥 Make app faster",completed: false,})}/>)}

📚 Docs

See the Usage guide for more details, including how to do:

• real-time sync
• cross-collection queries
• fine-grained reactivity
• different strategies for data loading and handling mutations

There's also an example React todo app and usage examples in the package tests.

🧱 Core concepts

Collections

• typed sets of objects that can mirror a backend table or be populated with a filtered view or result set, such as pendingTodos or decemberNewTodos
• collections are just JavaScript data — load them on demand and define as many as you need

Live queries

• run reactively against and across collections with support for joins, filters and aggregates
• powered by differential dataflow: query results update incrementally, not by re-running the whole query

Transactional mutators

• batch and stage local changes across collections with immediate application of local optimistic updates
• sync transactions to the backend with automatic rollbacks and management of optimistic state

📦 Collection Types

TanStack DB provides several collection types to support different backend integrations:

• @tanstack/db - Core collection functionality with local-only and local-storage collections for offline-first applications
• @tanstack/query-db-collection - Collections backed by TanStack Query for REST APIs and GraphQL endpoints
• @tanstack/electric-db-collection - Real-time sync collections powered by ElectricSQL for live database synchronization
• @tanstack/trailbase-db-collection - Collections for TrailBase backend integration

Framework integrations

TanStack DB integrates with React & Vue with more on the way!

• @tanstack/react-db - React hooks and components for using TanStack DB collections in React applications
• @tanstack/vue-db - Vue composables for using TanStack DB collections in Vue applications

🔧 Install

npm install @tanstack/react-db
# Optional: for specific collection types
npm install @tanstack/electric-db-collection @tanstack/query-db-collection

Other framework integrations are in progress.

❓ FAQ

How is this different from TanStack Query?
TanStack DB builds on top of TanStack Query. Use Query to fetch data; use DB to manage reactive local collections and mutations. They complement each other.

Do I need a sync engine like ElectricSQL?
No. TanStack DB is designed to work with sync engines like Electric but also works with any backend: polling APIs, GraphQL, REST, or custom sync logic.

What is a Collection? Is it like a DB table?
Kind of. Collections are typed sets of objects, but they can also be filtered views or custom groupings. They're just JavaScript structures that you define and manage.

Is this an ORM? Do queries hit my backend?
No. TanStack DB is not an ORM. Queries run entirely in the client against local collections. The framework provides strong primitives to manage how data is loaded and synced.

Partners

Status

Tanstack DB is currently in BETA. See the release post for more details.

Contributing

View the contributing guidelines here.

Become a Sponsor!