From f8302421ee7cd1063780a3ea1518000381245419 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Nov 2025 19:15:34 +0000 Subject: [PATCH 1/3] Enhance overview.md with blog post content and Query-Driven Sync Updates the overview documentation to better reflect the content and features from the two DB blog posts (0.1 and 0.5): - Add compelling "Option C" narrative explaining the architecture problem TanStack DB solves (view-specific APIs vs load-everything) - Document Query-Driven Sync feature from 0.5 release: - Three sync modes: eager, on-demand, progressive - How component queries automatically become API calls - Request optimization (collapsing, delta loading, join batching) - Add concrete performance numbers: ~0.7ms updates for 100k items on M1 Pro, demonstrating truly instantaneous optimistic updates - Expand sync engine benefits section: - Easy real-time updates without WebSocket plumbing - Automatic side-effects and cache invalidation - Efficient delta updates enabling "load everything once" pattern These changes bridge the gap between the technical reference docs and the compelling narrative from the blog posts, helping developers understand both why TanStack DB exists and how to use it effectively. --- docs/overview.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-) diff --git a/docs/overview.md b/docs/overview.md index 7d672f035..01e2c45cc 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -7,7 +7,14 @@ id: overview Welcome to the TanStack DB documentation. -TanStack DB is the reactive client-first store for your API. Stop building custom endpoints for every view—TanStack 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. +TanStack DB is the reactive client-first store for your API. **Stop building custom endpoints for every view**—TanStack 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. + +It solves the architecture problem most teams face: + +- **View-specific APIs** = endpoint sprawl and network waterfalls +- **Load-everything-and-filter** = sluggish client performance + +TanStack DB enables **Option C**: load normalized collections, then perform sub-millisecond incremental joins in the client. Your queries adapt to what data loads, your components get instant updates, and your backend stays simple. It extends TanStack Query with collections, live queries and optimistic mutations, working seamlessly with REST APIs, sync engines, or any data source. @@ -71,11 +78,41 @@ Collections can be populated in many ways, including: Once you have your data in collections, you can query across them using live queries in your components. +#### Sync Modes + +Collections support three sync modes to optimize data loading: + +- **Eager mode** (default): Loads entire collection upfront. Best for <10k rows of mostly static data like user preferences or small reference tables. +- **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. +- **Progressive mode**: Loads query subset immediately, syncs full dataset in background. Best for collaborative apps needing instant first paint AND sub-millisecond queries. + +With on-demand mode, your component's query becomes the API call: + +```tsx +const productsCollection = createCollection( + queryCollectionOptions({ + queryKey: ['products'], + queryFn: async (ctx) => { + // Query predicates passed automatically in ctx.meta + const params = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions) + return api.getProducts(params) // e.g., GET /api/products?category=electronics&price_lt=100 + }, + syncMode: 'on-demand', // ← Enable query-driven sync + }) +) +``` + +TanStack 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. + +See the [Query Collection documentation](../collections/query-collection.md#queryfn-and-predicate-push-down) for full predicate mapping details. + ### Using live queries Live 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. -TanStack 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. +TanStack 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. + +**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. Live queries support joins across collections. This allows you to: @@ -412,6 +449,16 @@ This pattern allows you to extend an existing TanStack Query application, or any One 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. +#### Why Sync Engines? + +While TanStack DB works great with REST APIs, sync engines provide powerful benefits: + +- **Easy real-time updates**: No WebSocket plumbing—write to your database and changes stream automatically to all clients +- **Automatic side-effects**: When a mutation triggers cascading changes across tables, all affected data syncs automatically without manual cache invalidation +- **Efficient delta updates**: Only changed rows cross the wire, making it practical to load large datasets client-side + +This pattern enables the "load everything once" approach that makes apps like Linear and Figma feel instant. + Here, we illustrate this pattern using [ElectricSQL](https://electric-sql.com) as the sync engine. ```tsx From af29df11da10f13483a186e617166e510ba44fb2 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Nov 2025 19:34:09 +0000 Subject: [PATCH 2/3] Add end-user benefit emphasis: apps stay fast regardless of data size Highlights that apps can't get sluggish due to too much data, with queries over 100k+ rows completing in under a millisecond. This makes the end-user experience benefit clear early in the documentation. --- docs/overview.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/overview.md b/docs/overview.md index 01e2c45cc..42c750ce1 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -16,6 +16,8 @@ It solves the architecture problem most teams face: TanStack DB enables **Option C**: load normalized collections, then perform sub-millisecond incremental joins in the client. Your queries adapt to what data loads, your components get instant updates, and your backend stays simple. +**The end-user benefit:** Your app stays blazing fast no matter how much data you load. Apps can't get sluggish due to too much data—queries over 100,000+ rows complete in under a millisecond, making interactions feel truly instantaneous. + It extends TanStack Query with collections, live queries and optimistic mutations, working seamlessly with REST APIs, sync engines, or any data source. ## Contents From a3959cc4256ba0d3a8f272a730ef3e93b5bce74d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Nov 2025 23:03:29 +0000 Subject: [PATCH 3/3] Refine introduction with clearer problem-solution framing Rewrites the introduction to: - Lead with the problems TanStack DB solves (endpoint sprawl, client performance, network on interaction path) - Emphasize the end-user benefit upfront: interactions feel instantaneous, app stays fast regardless of data volume - Present the "new way" as numbered benefits rather than "Option C" framing - More action-oriented and benefit-focused language This makes the value proposition clearer and more compelling for developers evaluating TanStack DB. --- docs/overview.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/overview.md b/docs/overview.md index 42c750ce1..40a80e89a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -7,16 +7,28 @@ id: overview Welcome to the TanStack DB documentation. -TanStack DB is the reactive client-first store for your API. **Stop building custom endpoints for every view**—TanStack 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. +TanStack DB is the reactive client store for your API. It solves the problems of building fast, modern apps, helping you: -It solves the architecture problem most teams face: +- avoid endpoint sprawl and network waterfalls by loading data into normalized collections +- optimise client performance with sub-millisecond live queries and real-time reactivity +- take the network off the interaction path with instant optimistic writes -- **View-specific APIs** = endpoint sprawl and network waterfalls -- **Load-everything-and-filter** = sluggish client performance +Data loading is optimized. Interactions feel instantaneous. Your backend stays simple and your app stays blazing fast. No matter how much data you load. -TanStack DB enables **Option C**: load normalized collections, then perform sub-millisecond incremental joins in the client. Your queries adapt to what data loads, your components get instant updates, and your backend stays simple. +## Remove the complexity from building fast, modern apps -**The end-user benefit:** Your app stays blazing fast no matter how much data you load. Apps can't get sluggish due to too much data—queries over 100,000+ rows complete in under a millisecond, making interactions feel truly instantaneous. +TanStack 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. + +Instead of choosing between the least of two evils: + +1. **view-specific APIs** - complicating your backend and leading to network waterfalls +2. **load everything and filter** - leading to slow loads and sluggish client performance + +TanStack DB enables a new way: + +3. **normalized collections** - keep your backend simple +4. **query-driven sync** - optimizes your data loading +5. **sub-millisecond live queries** - keep your app fast and responsive It extends TanStack Query with collections, live queries and optimistic mutations, working seamlessly with REST APIs, sync engines, or any data source.