https://github.com/TanStack/db
A reactive client store for building super fast apps on sync
https://github.com/TanStack/db
Last synced: 7 months ago
JSON representation
A reactive client store for building super fast apps on sync
- Host: GitHub
- URL: https://github.com/TanStack/db
- Owner: TanStack
- License: mit
- Created: 2025-03-11T21:01:29.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-06-11T15:18:02.000Z (7 months ago)
- Last Synced: 2025-06-11T15:32:27.137Z (7 months ago)
- Language: TypeScript
- Homepage: https://tanstack.com/db
- Size: 958 KB
- Stars: 2,483
- Watchers: 12
- Forks: 37
- Open Issues: 51
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://tanstack.com), including [TanStack Query](https://tanstack.com/query), [TanStack Store](https://tanstack.com/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 ([#](https://github.com/electric-sql/d2ts)), 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](https://tanstack.com/store), works with and alongside [TanStack Query](https://tanstack.com/query)
## 💥 Usage example
Sync data into collections:
```ts
import { createQueryCollection } from "@tanstack/db-collections"
const todoCollection = createQueryCollection({
queryKey: ["todos"],
queryFn: async () => fetch("/api/todos"),
getId: (item) => item.id,
schema: todoSchema, // any standard schema
})
```
Use live queries in your components:
```tsx
import { useLiveQuery } from "@tanstack/react-db"
const Todos = () => {
const { data: todos } = useLiveQuery((query) =>
query.from({ todoCollection }).where("@completed", "=", false)
)
return
}
```
Apply mutations with local optimistic state:
```tsx
// Define collection with persistence handlers
const todoCollection = createCollection({
id: "todos",
// ... other config
onInsert: async ({ transaction }) => {
const modified = transaction.mutations[0].modified
await api.todos.create(modified)
},
})
// Then use collection operators in your components
const AddTodo = () => {
return (
todoCollection.insert({
id: uuid(),
text: "🔥 Make app faster",
completed: false,
})
}
/>
)
}
```
## 📚 Docs
See the [Usage guide](./docs/overview.md) 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](./examples/react/todo) and usage examples in the [package tests](./packages/db/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
```bash
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](https://electric-sql.com) 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](https://github.com/TanStack/query/blob/main/CONTRIBUTING.md).
### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)