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 { createQueryCollection } from "@tanstack/db-collections"

const todoCollection = createQueryCollection<Todo>({
  queryKey: ["todos"],
  queryFn: async () => fetch("/api/todos"),
  getId: (item) => item.id,
  schema: todoSchema, // any standard schema
})

Use live queries in your components:

import { useLiveQuery } from "@tanstack/react-db"

const Todos = () => {
  const { data: todos } = useLiveQuery((query) =>
    query.from({ todoCollection }).where("@completed", "=", false)
  )

  return <List items={todos} />
}

Apply transactional writes with local optimistic state:

import { useOptimisticMutation } from "@tanstack/react-db"

const AddTodo = () => {
  const addTodo = useOptimisticMutation({
    mutationFn: async ({ transaction }) => {
      const { collection, modified: newTodo } = transaction.mutations[0]!

      await api.todos.create(newTodo)
      await collection.refetch()
    },
  })

  return (
    <Button
      onClick={() =>
        addTodo.mutate(() =>
          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

🔧 Install

npm install @tanstack/react-db @tanstack/db-collections

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 an early preview release in alpha. It's still under active development. There will be bugs and the APIs are still liable to change.

Contributing

View the contributing guidelines here.

Become a Sponsor!

License

melkir/db

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages