Open History to see the last commit
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)
70}
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 )
97}
98
99const dbClient = new DbClient()
100
101const App = () => (
102 <DbProvider client={dbClient}>
103 <Todos />
104 </DbProvider>
105)
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 })
145)
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)** — Load data into collections using TanStack Query for REST APIs and data fetching.
220
221**Sync Collections**
222
223- **[ElectricCollection](./collections/electric-collection.md)** — Sync data into collections from Postgres using ElectricSQL's real-time sync engine.
224
225- **[TrailBaseCollection](./collections/trailbase-collection.md)** — Sync data into collections using TrailBase's self-hosted backend with real-time subscriptions.
226
227- **[RxDBCollection](./collections/rxdb-collection.md)** — Integrate with RxDB for offline-first local persistence with powerful replication and sync capabilities.
228
229- **[PowerSyncCollection](./collections/powersync-collection.md)** — 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)** — Store small amounts of local-only state that persists across sessions and syncs across browser tabs.
234
235- **[LocalOnlyCollection](./collections/local-only-collection.md)** — 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 })
266)
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 } />
317}
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 } />
345}
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 } />
366}
367
368const App = () => (
369 <Suspense fallback={<div>Loading...</div>}>
370 <Todos />
371 </Suspense>
372)
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 })
465)
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 })
483)
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 // ...
507}
508
509const App = () => (
510 <DbProvider client={dbClient}>
511 <Todos />
512 </DbProvider>
513)
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 })
562)
563
564const AddTodo = () => {
565 const todosCollection = useDbClient().collection(todoCollection)
566
567 return (
568 <Button
569 onClick={() => todosCollection.insert({ text: "🔥 Make app faster" })}
570 />
571 )
572}
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)