Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

overview.md

598 lines23.3 KB

1---
2title: Overview
3id: overview
4---
5​
6# TanStack DB - Documentation
7​
8Welcome to the TanStack DB documentation.
9​
10TanStack DB is the reactive client store for your API. It solves the problems of building fast, modern apps, helping you:
11​
12- avoid endpoint sprawl and network waterfalls by loading data into normalized collections
13- optimise client performance with sub-millisecond live queries and real-time reactivity
14- take the network off the interaction path with instant optimistic writes
15​
16Data loading is optimized. Interactions feel instantaneous. Your backend stays simple and your app stays blazing fast. No matter how much data you load.
17​
18## Remove the complexity from building fast, modern apps
19​
20TanStack DB lets you query your data however your components need it, with a blazing-fast local query engine, real-time reactivity and instant optimistic updates.
21​
22Instead of choosing between the least of two evils:
23​
241. **view-specific APIs** - complicating your backend and leading to network waterfalls
252. **load everything and filter** - leading to slow loads and sluggish client performance
26​
27TanStack DB enables a new way:
28​
293. **normalized collections** - keep your backend simple
304. **query-driven sync** - optimizes your data loading
315. **sub-millisecond live queries** - keep your app fast and responsive
32​
33It extends TanStack Query with collections, live queries and optimistic mutations, working seamlessly with REST APIs, sync engines, or any data source.
34​
35## Contents
36​
37- [How it works](#how-it-works) — understand the TanStack DB development model and how the pieces fit together
38- [SSR and hydration](./guides/ssr.md) — use `DbClient` to transport explicit collection rows or live-query result snapshots
39- [API reference](#api-reference) — for the primitives and function interfaces
40- [Usage examples](#usage-examples) — examples of common usage patterns
41- [More info](#more-info) — where to find support and more information
42​
43## How it works
44​
45TanStack DB works by:
46​
47- [defining collections](#defining-collections) typed sets of objects that can be populated with data
48- [using live queries](#using-live-queries) to query data from/across collections
49- [making optimistic mutations](#making-optimistic-mutations) using transactional mutators
50​
51```tsx
52import {
53 DbClient,
54 DbProvider,
55 collectionOptions,
56 not,
57 useDbClient,
58 useLiveQuery,
59} from '@tanstack/react-db'
60​
61// Define stable collection descriptors to load data into
62const todoCollection = collectionOptions('todos', () => ({
63 id: 'todos',
64 // ...your config
65 onUpdate: updateMutationFn,
66}))
67​
68function useTodoCollection() {
69 return useDbClient().collection(todoCollection)
71​
72const Todos = () => {
73 const todosCollection = useTodoCollection()
74​
75 // Bind data using live queries
76 const { data: todos } = useLiveQuery({
77 query: (q) =>
78 q.from({ todo: todoCollection }).where(({ todo }) => not(todo.completed)),
79 })
80​
81 const complete = (todo) => {
82 // Instantly applies optimistic state
83 todosCollection.update(todo.id, (draft) => {
84 draft.completed = true
85 })
86 }
87​
88 return (
89 <ul>
90 {todos.map((todo) => (
91 <li key={todo.id} onClick={() => complete(todo)}>
92 {todo.text}
93 </li>
94 ))}
95 </ul>
96 )
98​
99const dbClient = new DbClient()
100​
101const App = () => (
102 <DbProvider client={dbClient}>
103 <Todos />
104 </DbProvider>
106```
107​
108### Defining collections
109​
110Collections are typed sets of objects that can be populated with data. They're designed to de-couple loading data into your app from binding data to your components.
111​
112Collections can be populated in many ways, including:
113​
114- fetching data, for example [from API endpoints using TanStack Query](https://tanstack.com/query/latest)
115- syncing data, for example [using a sync engine like ElectricSQL](https://electric-sql.com/) or [PowerSync](https://powersync.com)
116- storing local data, for example [using localStorage for user preferences and settings](./collections/local-storage-collection.md) or [in-memory client data or UI state](./collections/local-only-collection.md)
117- from live collection queries, creating [derived collections as materialised views](#using-live-queries)
118​
119Once you have your data in collections, you can query across them using live queries in your components.
120​
121#### Sync Modes
122​
123Collections support three sync modes to optimize data loading:
124​
125- **Eager mode** (default): Loads entire collection upfront. Best for <10k rows of mostly static data like user preferences or small reference tables.
126- **On-demand mode**: Loads only what queries request. Best for large datasets (>50k rows), search interfaces, and catalogs where most data won't be accessed.
127- **Progressive mode**: Loads query subset immediately, syncs full dataset in background. Best for collaborative apps needing instant first paint AND sub-millisecond queries.
128​
129With on-demand mode, your component's query becomes the API call:
130​
131```tsx
132const productsCollection = collectionOptions('products', (client) =>
133 queryCollectionOptions({
134 id: 'products',
135 queryKey: ['products'],
136 queryClient: client.requireDependency<QueryClient>('queryClient'),
137 queryFn: async (ctx) => {
138 // Query predicates passed automatically in ctx.meta
139 const params = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions)
140 return api.getProducts(params) // e.g., GET /api/products?category=electronics&price_lt=100
141 },
142 getKey: (product) => product.id,
143 syncMode: 'on-demand', // ← Enable query-driven sync
144 })
146```
147​
148TanStack DB automatically collapses duplicate requests, performs delta loading when expanding queries, optimizes joins into minimal batched requests, and respects your TanStack Query cache policies. You often end up with _fewer_ network requests than custom view-specific APIs.
149​
150See the [Query Collection documentation](./collections/query-collection.md#queryfn-and-predicate-push-down) for full predicate mapping details.
151​
152### Using live queries
153​
154Live queries are used to query data out of collections. Live queries are reactive: when the underlying data changes in a way that would affect the query result, the result is incrementally updated and returned from the query, triggering a re-render.
155​
156TanStack DB live queries are implemented using [d2ts](https://github.com/electric-sql/d2ts), a TypeScript implementation of differential dataflow. This allows the query results to update _incrementally_ (rather than by re-running the whole query). This makes them blazing fast, usually sub-millisecond, even for highly complex queries.
157​
158**Performance:** Updating one row in a sorted 100,000-item collection completes in ~0.7ms on an M1 Pro MacBook—fast enough that optimistic updates feel truly instantaneous, even with complex queries and large datasets.
159​
160Live queries support joins across collections. This allows you to:
161​
1621. load normalised data into collections and then de-normalise it through queries; simplifying your backend by avoiding the need for bespoke API endpoints that match your client
1632. join data from multiple sources; for example, syncing some data out of a database, fetching some other data from an external API and then joining these into a unified data model for your front-end code
164​
165Every query returns another collection which can _also_ be queried.
166​
167For more details on live queries, see the [Live Queries](./guides/live-queries.md) documentation.
168​
169### Making optimistic mutations
170​
171Collections support `insert`, `update` and `delete` operations. When called, by default they trigger the corresponding `onInsert`, `onUpdate`, `onDelete` handlers which are responsible for writing the mutation to the backend.
172​
173```ts
174// Define collection with persistence handlers
175const todoCollection = collectionOptions('todos', () => ({
176 id: "todos",
177 // ... other config
178 onUpdate: async ({ transaction }) => {
179 const { original, changes } = transaction.mutations[0]
180 await api.todos.update(original.id, changes)
181 },
182}))
183const todosCollection = dbClient.collection(todoCollection)
184​
185// Immediately applies optimistic state
186todosCollection.update(todo.id, (draft) => {
187 draft.completed = true
188})
189```
190​
191The collection maintains optimistic state separately from synced data. When live queries read from the collection, they see a local view that overlays the optimistic mutations on top of the immutable synced data.
192​
193The optimistic state is held until the handler resolves, at which point the data is persisted to the server and synced back. If the handler throws an error, the optimistic state is rolled back.
194​
195For more complex mutations, you can create custom actions with `createOptimisticAction` or custom transactions with `createTransaction`. See the [Mutations guide](./guides/mutations.md) for details.
196​
197### Uni-directional data flow
198​
199This combines to support a model of uni-directional data flow, extending the redux/flux style state management pattern beyond the client, to take in the server as well:
200​
201<figure>
202 <a href="https://raw.githubusercontent.com/TanStack/db/main/docs/unidirectional-data-flow.lg.png" target="_blank">
203 <img src="https://raw.githubusercontent.com/TanStack/db/main/docs/unidirectional-data-flow.png" />
204 </a>
205</figure>
206​
207With an instant inner loop of optimistic state, superseded in time by the slower outer loop of persisting to the server and syncing the updated server state back into the collection.
208​
209## API reference
210​
211### Collections
212​
213TanStack DB provides several built-in collection types for different data sources and use cases. Each collection type has its own detailed documentation page:
214​
215#### Built-in Collection Types
216​
217**Fetch Collections**
218​
219- **[QueryCollection](./collections/query-collection.md)** &mdash; Load data into collections using TanStack Query for REST APIs and data fetching.
220​
221**Sync Collections**
222​
223- **[ElectricCollection](./collections/electric-collection.md)** &mdash; Sync data into collections from Postgres using ElectricSQL's real-time sync engine.
224​
225- **[TrailBaseCollection](./collections/trailbase-collection.md)** &mdash; Sync data into collections using TrailBase's self-hosted backend with real-time subscriptions.
226​
227- **[RxDBCollection](./collections/rxdb-collection.md)** &mdash; Integrate with RxDB for offline-first local persistence with powerful replication and sync capabilities.
228​
229- **[PowerSyncCollection](./collections/powersync-collection.md)** &mdash; Sync with PowerSync's SQLite-based database for offline-first persistence with real-time synchronization with PostgreSQL, MongoDB, and MySQL backends.
230​
231**Local Collections**
232​
233- **[LocalStorageCollection](./collections/local-storage-collection.md)** &mdash; Store small amounts of local-only state that persists across sessions and syncs across browser tabs.
234​
235- **[LocalOnlyCollection](./collections/local-only-collection.md)** &mdash; Manage in-memory client data or UI state that doesn't need persistence or cross-tab sync.
236​
237#### Collection Schemas
238​
239All collections optionally (though strongly recommended) support adding a `schema`.
240​
241If provided, this must be a [Standard Schema](https://standardschema.dev) compatible schema instance, such as [Zod](https://zod.dev), [Valibot](https://valibot.dev), [ArkType](https://arktype.io), or [Effect](https://effect.website/docs/schema/introduction/).
242​
243**What schemas do:**
244​
2451. **Runtime validation** - Ensures data meets your constraints before entering the collection
2462. **Type transformations** - Convert input types to rich output types (e.g., string → Date)
2473. **Default values** - Automatically populate missing fields
2484. **Type safety** - Infer TypeScript types from your schema
249​
250**Example:**
251```typescript
252const todoSchema = z.object({
253 id: z.string(),
254 text: z.string(),
255 completed: z.boolean().default(false),
256 created_at: z.string().transform(val => new Date(val)), // string → Date
257 priority: z.number().default(0)
258})
259​
260const todoCollection = collectionOptions(
261 queryCollectionOptions({
262 id: "todos",
263 schema: todoSchema,
264 // ...
265 })
267const collection = dbClient.collection(todoCollection)
268​
269// Users provide simple inputs
270collection.insert({
271 id: "1",
272 text: "Buy groceries",
273 created_at: "2024-01-01T00:00:00Z" // string
274 // completed and priority filled automatically
275})
276​
277// Collection stores and returns rich types
278const todo = collection.get("1")
279console.log(todo.created_at.getFullYear()) // It's a Date!
280console.log(todo.completed) // false (default)
281```
282​
283The collection will use the schema for its type inference. If you provide a schema, you cannot also pass an explicit type parameter (e.g., `createCollection<Todo>()`).
284​
285**Learn more:** See the [Schemas guide](./guides/schemas.md) for comprehensive documentation on schema validation, type transformations, and best practices.
286​
287#### Creating Custom Collection Types
288​
289You can create your own collection types by implementing the `Collection` interface found in [`../packages/db/src/collection/index.ts`](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts).
290​
291See the existing implementations in [`../packages/db`](https://github.com/TanStack/db/tree/main/packages/db), [`../packages/query-db-collection`](https://github.com/TanStack/db/tree/main/packages/query-db-collection), [`../packages/electric-db-collection`](https://github.com/TanStack/db/tree/main/packages/electric-db-collection), [`../packages/trailbase-db-collection`](https://github.com/TanStack/db/tree/main/packages/trailbase-db-collection) and [`../packages/powersync-db-collection`](https://github.com/TanStack/db/tree/main/packages/powersync-db-collection) for reference. Also see the [Collection Options Creator guide](./guides/collection-options-creator.md) for a pattern to create reusable collection configuration factories.
292​
293### Live queries
294​
295#### `useLiveQuery` hook
296​
297Use the `useLiveQuery` hook to assign live query results to a state variable in your React components:
298​
299```ts
300import { useLiveQuery } from '@tanstack/react-db'
301import { eq } from '@tanstack/db'
302​
303const Todos = () => {
304 const { data: todos } = useLiveQuery({
305 query: (q) =>
306 q
307 .from({ todo: todoCollection })
308 .where(({ todo }) => eq(todo.completed, false))
309 .orderBy(({ todo }) => todo.created_at, 'asc')
310 .select(({ todo }) => ({
311 id: todo.id,
312 text: todo.text
313 })),
314 })
315​
316 return <List items={ todos } />
318```
319​
320You can also query across collections with joins:
321​
322```ts
323import { useLiveQuery } from '@tanstack/react-db'
324import { eq } from '@tanstack/db'
325​
326const Todos = () => {
327 const { data: todos } = useLiveQuery({
328 query: (q) =>
329 q
330 .from({ todos: todoCollection })
331 .join(
332 { lists: listCollection },
333 ({ todos, lists }) => eq(lists.id, todos.listId),
334 'inner'
335 )
336 .where(({ lists }) => eq(lists.active, true))
337 .select(({ todos, lists }) => ({
338 id: todos.id,
339 title: todos.title,
340 listName: lists.name
341 })),
342 })
343​
344 return <List items={ todos } />
346```
347​
348#### `useLiveSuspenseQuery` hook
349​
350For React Suspense support, use `useLiveSuspenseQuery`. This hook suspends rendering during initial data load and guarantees that `data` is always defined:
351​
352```tsx
353import { useLiveSuspenseQuery } from '@tanstack/react-db'
354import { Suspense } from 'react'
355​
356const Todos = () => {
357 // data is always defined - no need for optional chaining
358 const { data: todos } = useLiveSuspenseQuery({
359 query: (q) =>
360 q
361 .from({ todo: todoCollection })
362 .where(({ todo }) => eq(todo.completed, false)),
363 })
364​
365 return <List items={ todos } />
367​
368const App = () => (
369 <Suspense fallback={<div>Loading...</div>}>
370 <Todos />
371 </Suspense>
373```
374​
375See the [React Suspense section in Live Queries](./guides/live-queries#using-with-react-suspense) for detailed usage patterns and when to use `useLiveSuspenseQuery` vs `useLiveQuery`.
376​
377#### `queryBuilder`
378​
379You can also build queries directly (outside of the component lifecycle) using the underlying `queryBuilder` API:
380​
381```ts
382import { createLiveQueryCollection, eq } from "@tanstack/db"
383​
384const completedTodos = createLiveQueryCollection({
385 startSync: true,
386 query: (q) =>
387 q
388 .from({ todo: todoCollection })
389 .where(({ todo }) => eq(todo.completed, true)),
390})
391​
392const results = completedTodos.toArray
393```
394​
395Note also that:
396​
3971. the query results [are themselves a collection](#derived-collections)
3982. the `useLiveQuery` automatically starts and stops live query subscriptions when you mount and unmount your components; if you're creating queries manually, you need to manually manage the subscription lifecycle yourself
399​
400See the [Live Queries](./guides/live-queries.md) documentation for more details.
401​
402### Transactional mutators
403​
404For more complex mutations beyond simple CRUD operations, TanStack DB provides `createOptimisticAction` and `createTransaction` for creating custom mutations with full control over the mutation lifecycle.
405​
406See the [Mutations guide](./guides/mutations.md) for comprehensive documentation on:
407​
408- Creating custom actions with `createOptimisticAction`
409- Manual transactions with `createTransaction`
410- Mutation merging behavior
411- Controlling optimistic vs non-optimistic updates
412- Handling temporary IDs
413- Transaction lifecycle states
414​
415## Usage examples
416​
417Here we illustrate two common ways of using TanStack DB:
418​
4191. [using TanStack Query](#1-tanstack-query) with an existing REST API
4202. [using a sync engine](#2-sync-engine) for real-time sync with your backend
421​
422> [!TIP]
423> You can combine these patterns. One of the benefits of TanStack DB is that you can integrate different ways of loading data and handling mutations into the same app. Your components don't need to know where the data came from or goes.
424​
425### 1. TanStack Query
426​
427You can use TanStack DB with your existing REST API via TanStack Query.
428​
429The steps are to:
430​
4311. create [QueryCollection](./collections/query-collection.md)s that load data using TanStack Query
4322. implement mutation handlers that handle mutations by posting them to your API endpoints
433​
434```tsx
435import {
436 DbClient,
437 DbProvider,
438 collectionOptions,
439 useLiveQuery,
440} from "@tanstack/react-db"
441import { queryCollectionOptions } from "@tanstack/query-db-collection"
442import { QueryClient } from "@tanstack/query-core"
443​
444const queryClient = new QueryClient()
445const dbClient = new DbClient({ queryClient })
446​
447// Load data into collections using TanStack Query.
448// It's common to define these in a `collections` module.
449const todoCollection = collectionOptions("todos", (client) =>
450 queryCollectionOptions({
451 id: "todos",
452 queryKey: ["todos"],
453 queryClient: client.requireDependency<QueryClient>("queryClient"),
454 queryFn: async () => fetch("/api/todos").then((response) => response.json()),
455 getKey: (item) => item.id,
456 schema: todoSchema, // any standard schema
457 onInsert: async ({ transaction }) => {
458 const { changes: newTodo } = transaction.mutations[0]
459​
460 // Handle the local write by sending it to your API.
461 await api.todos.create(newTodo)
462 },
463 // also add onUpdate, onDelete as needed.
464 })
466const listCollection = collectionOptions("todo-lists", (client) =>
467 queryCollectionOptions({
468 id: "todo-lists",
469 queryKey: ["todo-lists"],
470 queryClient: client.requireDependency<QueryClient>("queryClient"),
471 queryFn: async () =>
472 fetch("/api/todo-lists").then((response) => response.json()),
473 getKey: (item) => item.id,
474 schema: todoListSchema,
475 onInsert: async ({ transaction }) => {
476 const { changes: newTodo } = transaction.mutations[0]
477​
478 // Handle the local write by sending it to your API.
479 await api.todoLists.create(newTodo)
480 },
481 // also add onUpdate, onDelete as needed.
482 })
484​
485const Todos = () => {
486 // Read the data using live queries. Here we show a live
487 // query that joins across two collections.
488 const { data: todos } = useLiveQuery({
489 query: (q) =>
490 q
491 .from({ todo: todoCollection })
492 .join(
493 { list: listCollection },
494 ({ todo, list }) => eq(list.id, todo.list_id),
495 "inner"
496 )
497 .where(({ list }) => eq(list.active, true))
498 .select(({ todo, list }) => ({
499 id: todo.id,
500 text: todo.text,
501 status: todo.status,
502 listName: list.name,
503 })),
504 })
505​
506 // ...
508​
509const App = () => (
510 <DbProvider client={dbClient}>
511 <Todos />
512 </DbProvider>
514```
515​
516This pattern allows you to extend an existing TanStack Query application, or any application built on a REST API, with blazing fast, cross-collection live queries and local optimistic mutations with automatically managed optimistic state.
517​
518### 2. Sync Engine
519​
520One of the most powerful ways of using TanStack DB is with a sync engine, for a fully local-first experience with real-time sync. This allows you to incrementally adopt sync into an existing app, whilst still handling writes with your existing API.
521​
522#### Why Sync Engines?
523​
524While TanStack DB works great with REST APIs, sync engines provide powerful benefits:
525​
526- **Easy real-time updates**: No WebSocket plumbing—write to your database and changes stream automatically to all clients
527- **Automatic side-effects**: When a mutation triggers cascading changes across tables, all affected data syncs automatically without manual cache invalidation
528- **Efficient delta updates**: Only changed rows cross the wire, making it practical to load large datasets client-side
529​
530This pattern enables the "load everything once" approach that makes apps like Linear and Figma feel instant.
531​
532Here, we illustrate this pattern using [ElectricSQL](https://electric-sql.com) as the sync engine, but this pattern also works with other sync engines like [PowerSync](https://www.powersync.com/?utm_source=tanstack&utm_campaign=tanstack_partner), [RxDB](https://rxdb.info/), and [TrailBase](https://trailbase.io/).
533​
534```tsx
535import type {
536 MutationFn,
537 PendingMutation,
538} from "@tanstack/react-db"
539import { collectionOptions, useDbClient } from "@tanstack/react-db"
540import { electricCollectionOptions } from "@tanstack/electric-db-collection"
541​
542export const todoCollection = collectionOptions(
543 electricCollectionOptions({
544 id: "todos",
545 schema: todoSchema,
546 // Electric syncs data using "shapes". These are filtered views
547 // on database tables that Electric keeps in sync for you.
548 shapeOptions: {
549 url: "https://api.electric-sql.cloud/v1/shape",
550 params: {
551 table: "todos",
552 },
553 },
554 getKey: (item) => item.id,
555 onInsert: async ({ transaction }) => {
556 const response = await api.todos.create(transaction.mutations[0].modified)
557​
558 return { txid: response.txid }
559 },
560 // You can also implement onUpdate, onDelete as needed.
561 })
563​
564const AddTodo = () => {
565 const todosCollection = useDbClient().collection(todoCollection)
566​
567 return (
568 <Button
569 onClick={() => todosCollection.insert({ text: "🔥 Make app faster" })}
570 />
571 )
573```
574​
575## React Native
576​
577When using TanStack DB with React Native, you need to install and configure a UUID generation library since React Native doesn't include crypto.randomUUID() by default.
578​
579Install the `react-native-random-uuid` package:
580​
581```bash
582npm install react-native-random-uuid
583```
584​
585Then import it at the entry point of your React Native app (e.g., in your `App.js` or `index.js`):
586​
587```javascript
588import "react-native-random-uuid"
589```
590​
591This polyfill provides the `crypto.randomUUID()` function that TanStack DB uses internally for generating unique identifiers.
592​
593## More info
594​
595If you have questions / need help using TanStack DB, let us know on the Discord or start a GitHub discussion:
596​
597- [`#db` channel in the TanStack discord](https://discord.gg/yjUNbvbraC)
598- [GitHub discussions](https://github.com/tanstack/db/discussions)