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

overview.md

542 lines21.7 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- [API reference](#api-reference) — for the primitives and function interfaces
39- [Usage examples](#usage-examples) — examples of common usage patterns
40- [More info](#more-info) — where to find support and more information
41​
42## How it works
43​
44TanStack DB works by:
45​
46- [defining collections](#defining-collections) typed sets of objects that can be populated with data
47- [using live queries](#using-live-queries) to query data from/across collections
48- [making optimistic mutations](#making-optimistic-mutations) using transactional mutators
49​
50```tsx
51// Define collections to load data into
52const todoCollection = createCollection({
53 // ...your config
54 onUpdate: updateMutationFn,
55})
56​
57const Todos = () => {
58 // Bind data using live queries
59 const { data: todos } = useLiveQuery((q) =>
60 q.from({ todo: todoCollection }).where(({ todo }) => not(todo.completed))
61 )
62​
63 const complete = (todo) => {
64 // Instantly applies optimistic state
65 todoCollection.update(todo.id, (draft) => {
66 draft.completed = true
67 })
68 }
69​
70 return (
71 <ul>
72 {todos.map((todo) => (
73 <li key={todo.id} onClick={() => complete(todo)}>
74 {todo.text}
75 </li>
76 ))}
77 </ul>
78 )
80```
81​
82### Defining collections
83​
84Collections 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.
85​
86Collections can be populated in many ways, including:
87​
88- fetching data, for example [from API endpoints using TanStack Query](https://tanstack.com/query/latest)
89- syncing data, for example [using a sync engine like ElectricSQL](https://electric-sql.com/) or [PowerSync](https://powersync.com)
90- 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)
91- from live collection queries, creating [derived collections as materialised views](#using-live-queries)
92​
93Once you have your data in collections, you can query across them using live queries in your components.
94​
95#### Sync Modes
96​
97Collections support three sync modes to optimize data loading:
98​
99- **Eager mode** (default): Loads entire collection upfront. Best for <10k rows of mostly static data like user preferences or small reference tables.
100- **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.
101- **Progressive mode**: Loads query subset immediately, syncs full dataset in background. Best for collaborative apps needing instant first paint AND sub-millisecond queries.
102​
103With on-demand mode, your component's query becomes the API call:
104​
105```tsx
106const productsCollection = createCollection(
107 queryCollectionOptions({
108 queryKey: ['products'],
109 queryFn: async (ctx) => {
110 // Query predicates passed automatically in ctx.meta
111 const params = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions)
112 return api.getProducts(params) // e.g., GET /api/products?category=electronics&price_lt=100
113 },
114 syncMode: 'on-demand', // ← Enable query-driven sync
115 })
117```
118​
119TanStack 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.
120​
121See the [Query Collection documentation](./collections/query-collection.md#queryfn-and-predicate-push-down) for full predicate mapping details.
122​
123### Using live queries
124​
125Live 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.
126​
127TanStack 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.
128​
129**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.
130​
131Live queries support joins across collections. This allows you to:
132​
1331. 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
1342. 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
135​
136Every query returns another collection which can _also_ be queried.
137​
138For more details on live queries, see the [Live Queries](./guides/live-queries.md) documentation.
139​
140### Making optimistic mutations
141​
142Collections 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.
143​
144```ts
145// Define collection with persistence handlers
146const todoCollection = createCollection({
147 id: "todos",
148 // ... other config
149 onUpdate: async ({ transaction }) => {
150 const { original, changes } = transaction.mutations[0]
151 await api.todos.update(original.id, changes)
152 },
153})
154​
155// Immediately applies optimistic state
156todoCollection.update(todo.id, (draft) => {
157 draft.completed = true
158})
159```
160​
161The 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.
162​
163The 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.
164​
165For more complex mutations, you can create custom actions with `createOptimisticAction` or custom transactions with `createTransaction`. See the [Mutations guide](./guides/mutations.md) for details.
166​
167### Uni-directional data flow
168​
169This 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:
170​
171<figure>
172 <a href="https://raw.githubusercontent.com/TanStack/db/main/docs/unidirectional-data-flow.lg.png" target="_blank">
173 <img src="https://raw.githubusercontent.com/TanStack/db/main/docs/unidirectional-data-flow.png" />
174 </a>
175</figure>
176​
177With 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.
178​
179## API reference
180​
181### Collections
182​
183TanStack DB provides several built-in collection types for different data sources and use cases. Each collection type has its own detailed documentation page:
184​
185#### Built-in Collection Types
186​
187**Fetch Collections**
188​
189- **[QueryCollection](./collections/query-collection.md)** &mdash; Load data into collections using TanStack Query for REST APIs and data fetching.
190​
191**Sync Collections**
192​
193- **[ElectricCollection](./collections/electric-collection.md)** &mdash; Sync data into collections from Postgres using ElectricSQL's real-time sync engine.
194​
195- **[TrailBaseCollection](./collections/trailbase-collection.md)** &mdash; Sync data into collections using TrailBase's self-hosted backend with real-time subscriptions.
196​
197- **[RxDBCollection](./collections/rxdb-collection.md)** &mdash; Integrate with RxDB for offline-first local persistence with powerful replication and sync capabilities.
198​
199- **[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.
200​
201**Local Collections**
202​
203- **[LocalStorageCollection](./collections/local-storage-collection.md)** &mdash; Store small amounts of local-only state that persists across sessions and syncs across browser tabs.
204​
205- **[LocalOnlyCollection](./collections/local-only-collection.md)** &mdash; Manage in-memory client data or UI state that doesn't need persistence or cross-tab sync.
206​
207#### Collection Schemas
208​
209All collections optionally (though strongly recommended) support adding a `schema`.
210​
211If 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/).
212​
213**What schemas do:**
214​
2151. **Runtime validation** - Ensures data meets your constraints before entering the collection
2162. **Type transformations** - Convert input types to rich output types (e.g., string → Date)
2173. **Default values** - Automatically populate missing fields
2184. **Type safety** - Infer TypeScript types from your schema
219​
220**Example:**
221```typescript
222const todoSchema = z.object({
223 id: z.string(),
224 text: z.string(),
225 completed: z.boolean().default(false),
226 created_at: z.string().transform(val => new Date(val)), // string → Date
227 priority: z.number().default(0)
228})
229​
230const collection = createCollection(
231 queryCollectionOptions({
232 schema: todoSchema,
233 // ...
234 })
236​
237// Users provide simple inputs
238collection.insert({
239 id: "1",
240 text: "Buy groceries",
241 created_at: "2024-01-01T00:00:00Z" // string
242 // completed and priority filled automatically
243})
244​
245// Collection stores and returns rich types
246const todo = collection.get("1")
247console.log(todo.created_at.getFullYear()) // It's a Date!
248console.log(todo.completed) // false (default)
249```
250​
251The 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>()`).
252​
253**Learn more:** See the [Schemas guide](./guides/schemas.md) for comprehensive documentation on schema validation, type transformations, and best practices.
254​
255#### Creating Custom Collection Types
256​
257You 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).
258​
259See 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.
260​
261### Live queries
262​
263#### `useLiveQuery` hook
264​
265Use the `useLiveQuery` hook to assign live query results to a state variable in your React components:
266​
267```ts
268import { useLiveQuery } from '@tanstack/react-db'
269import { eq } from '@tanstack/db'
270​
271const Todos = () => {
272 const { data: todos } = useLiveQuery((q) =>
273 q
274 .from({ todo: todoCollection })
275 .where(({ todo }) => eq(todo.completed, false))
276 .orderBy(({ todo }) => todo.created_at, 'asc')
277 .select(({ todo }) => ({
278 id: todo.id,
279 text: todo.text
280 }))
281 )
282​
283 return <List items={ todos } />
285```
286​
287You can also query across collections with joins:
288​
289```ts
290import { useLiveQuery } from '@tanstack/react-db'
291import { eq } from '@tanstack/db'
292​
293const Todos = () => {
294 const { data: todos } = useLiveQuery((q) =>
295 q
296 .from({ todos: todoCollection })
297 .join(
298 { lists: listCollection },
299 ({ todos, lists }) => eq(lists.id, todos.listId),
300 'inner'
301 )
302 .where(({ lists }) => eq(lists.active, true))
303 .select(({ todos, lists }) => ({
304 id: todos.id,
305 title: todos.title,
306 listName: lists.name
307 }))
308 )
309​
310 return <List items={ todos } />
312```
313​
314#### `useLiveSuspenseQuery` hook
315​
316For React Suspense support, use `useLiveSuspenseQuery`. This hook suspends rendering during initial data load and guarantees that `data` is always defined:
317​
318```tsx
319import { useLiveSuspenseQuery } from '@tanstack/react-db'
320import { Suspense } from 'react'
321​
322const Todos = () => {
323 // data is always defined - no need for optional chaining
324 const { data: todos } = useLiveSuspenseQuery((q) =>
325 q
326 .from({ todo: todoCollection })
327 .where(({ todo }) => eq(todo.completed, false))
328 )
329​
330 return <List items={ todos } />
332​
333const App = () => (
334 <Suspense fallback={<div>Loading...</div>}>
335 <Todos />
336 </Suspense>
338```
339​
340See 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`.
341​
342#### `queryBuilder`
343​
344You can also build queries directly (outside of the component lifecycle) using the underlying `queryBuilder` API:
345​
346```ts
347import { createLiveQueryCollection, eq } from "@tanstack/db"
348​
349const completedTodos = createLiveQueryCollection({
350 startSync: true,
351 query: (q) =>
352 q
353 .from({ todo: todoCollection })
354 .where(({ todo }) => eq(todo.completed, true)),
355})
356​
357const results = completedTodos.toArray
358```
359​
360Note also that:
361​
3621. the query results [are themselves a collection](#derived-collections)
3632. 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
364​
365See the [Live Queries](./guides/live-queries.md) documentation for more details.
366​
367### Transactional mutators
368​
369For more complex mutations beyond simple CRUD operations, TanStack DB provides `createOptimisticAction` and `createTransaction` for creating custom mutations with full control over the mutation lifecycle.
370​
371See the [Mutations guide](./guides/mutations.md) for comprehensive documentation on:
372​
373- Creating custom actions with `createOptimisticAction`
374- Manual transactions with `createTransaction`
375- Mutation merging behavior
376- Controlling optimistic vs non-optimistic updates
377- Handling temporary IDs
378- Transaction lifecycle states
379​
380## Usage examples
381​
382Here we illustrate two common ways of using TanStack DB:
383​
3841. [using TanStack Query](#1-tanstack-query) with an existing REST API
3852. [using a sync engine](#2-sync-engine) for real-time sync with your backend
386​
387> [!TIP]
388> 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.
389​
390### 1. TanStack Query
391​
392You can use TanStack DB with your existing REST API via TanStack Query.
393​
394The steps are to:
395​
3961. create [QueryCollection](./collections/query-collection.md)s that load data using TanStack Query
3972. implement mutation handlers that handle mutations by posting them to your API endpoints
398​
399```tsx
400import { useLiveQuery, createCollection } from "@tanstack/react-db"
401import { queryCollectionOptions } from "@tanstack/query-db-collection"
402​
403// Load data into collections using TanStack Query.
404// It's common to define these in a `collections` module.
405const todoCollection = createCollection(
406 queryCollectionOptions({
407 queryKey: ["todos"],
408 queryFn: async () => fetch("/api/todos"),
409 getKey: (item) => item.id,
410 schema: todoSchema, // any standard schema
411 onInsert: async ({ transaction }) => {
412 const { changes: newTodo } = transaction.mutations[0]
413​
414 // Handle the local write by sending it to your API.
415 await api.todos.create(newTodo)
416 },
417 // also add onUpdate, onDelete as needed.
418 })
420const listCollection = createCollection(
421 queryCollectionOptions({
422 queryKey: ["todo-lists"],
423 queryFn: async () => fetch("/api/todo-lists"),
424 getKey: (item) => item.id,
425 schema: todoListSchema,
426 onInsert: async ({ transaction }) => {
427 const { changes: newTodo } = transaction.mutations[0]
428​
429 // Handle the local write by sending it to your API.
430 await api.todoLists.create(newTodo)
431 },
432 // also add onUpdate, onDelete as needed.
433 })
435​
436const Todos = () => {
437 // Read the data using live queries. Here we show a live
438 // query that joins across two collections.
439 const { data: todos } = useLiveQuery((q) =>
440 q
441 .from({ todo: todoCollection })
442 .join(
443 { list: listCollection },
444 ({ todo, list }) => eq(list.id, todo.list_id),
445 "inner"
446 )
447 .where(({ list }) => eq(list.active, true))
448 .select(({ todo, list }) => ({
449 id: todo.id,
450 text: todo.text,
451 status: todo.status,
452 listName: list.name,
453 }))
454 )
455​
456 // ...
458```
459​
460This 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.
461​
462### 2. Sync Engine
463​
464One 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.
465​
466#### Why Sync Engines?
467​
468While TanStack DB works great with REST APIs, sync engines provide powerful benefits:
469​
470- **Easy real-time updates**: No WebSocket plumbing—write to your database and changes stream automatically to all clients
471- **Automatic side-effects**: When a mutation triggers cascading changes across tables, all affected data syncs automatically without manual cache invalidation
472- **Efficient delta updates**: Only changed rows cross the wire, making it practical to load large datasets client-side
473​
474This pattern enables the "load everything once" approach that makes apps like Linear and Figma feel instant.
475​
476Here, 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/).
477​
478```tsx
479import type { Collection } from "@tanstack/db"
480import type {
481 MutationFn,
482 PendingMutation,
483 createCollection,
484} from "@tanstack/react-db"
485import { electricCollectionOptions } from "@tanstack/electric-db-collection"
486​
487export const todoCollection = createCollection(
488 electricCollectionOptions({
489 id: "todos",
490 schema: todoSchema,
491 // Electric syncs data using "shapes". These are filtered views
492 // on database tables that Electric keeps in sync for you.
493 shapeOptions: {
494 url: "https://api.electric-sql.cloud/v1/shape",
495 params: {
496 table: "todos",
497 },
498 },
499 getKey: (item) => item.id,
500 schema: todoSchema,
501 onInsert: async ({ transaction }) => {
502 const response = await api.todos.create(transaction.mutations[0].modified)
503​
504 return { txid: response.txid }
505 },
506 // You can also implement onUpdate, onDelete as needed.
507 })
509​
510const AddTodo = () => {
511 return (
512 <Button
513 onClick={() => todoCollection.insert({ text: "🔥 Make app faster" })}
514 />
515 )
517```
518​
519## React Native
520​
521When 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.
522​
523Install the `react-native-random-uuid` package:
524​
525```bash
526npm install react-native-random-uuid
527```
528​
529Then import it at the entry point of your React Native app (e.g., in your `App.js` or `index.js`):
530​
531```javascript
532import "react-native-random-uuid"
533```
534​
535This polyfill provides the `crypto.randomUUID()` function that TanStack DB uses internally for generating unique identifiers.
536​
537## More info
538​
539If you have questions / need help using TanStack DB, let us know on the Discord or start a GitHub discussion:
540​
541- [`#db` channel in the TanStack discord](https://discord.gg/yjUNbvbraC)
542- [GitHub discussions](https://github.com/tanstack/db/discussions)