Open History to see the last commit
1# TanStack DB — Skill Specification (Reviewed)
2
3TanStack DB is a reactive client-side data store that provides normalized collections, sub-millisecond live queries via differential dataflow (d2ts), and instant optimistic mutations with automatic rollback. It supports multiple data sources (REST APIs via TanStack Query, sync engines like ElectricSQL/PowerSync/RxDB/TrailBase, and local storage) through a unified collection API with framework adapters for React, Vue, Svelte, Solid, and Angular.
4
5## Domains
6
7| Domain | Description | Skills |
8| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------- |
9| Collection Setup & Schema | Creating and configuring typed collections from any data source, with schema validation and adapter-specific sync patterns | collection-setup |
10| Live Query Construction | Building SQL-like reactive queries with expressions, joins, aggregations, and incremental view maintenance | live-queries |
11| Framework Integration | Binding live queries to UI framework components using hooks, dependency tracking, Suspense, and pagination | framework-integration |
12| Mutations & Optimistic State | Writing data with instant optimistic feedback, transaction lifecycles, and automatic rollback | mutations-optimistic |
13| Meta-Framework Integration | Client-side preloading of collections in route loaders for TanStack Start, Next.js, Remix, etc. | meta-framework |
14| Custom Adapter Authoring | Building custom collection adapters that implement the SyncConfig contract | custom-adapter |
15| Offline Transactions | Offline-first transaction queueing with persistence, retry, and multi-tab coordination | offline |
16
17## Skill Inventory
18
19| Skill | Type | Domain | What it covers | Failure modes |
20| --------------------- | ----------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | :-----------: |
21| collection-setup | core | Collection Setup & Schema | createCollection, 7 adapter option creators, CollectionConfig, StandardSchema, lifecycle, sync modes, adapter-specific patterns | 10 |
22| live-queries | core | Live Query Construction | Query builder API, all operators, joins, aggregates, derived collections, IVM, $selected, predicate push-down | 8 |
23| framework-integration | framework | Framework Integration | React/Vue/Svelte/Solid/Angular hooks, deps arrays, Suspense, infinite queries | 4 |
24| mutations-optimistic | core | Mutations & Optimistic State | insert/update/delete, draft proxy, transactions, paced mutations, Pacer integration | 8 |
25| meta-framework | composition | Meta-Framework Integration | preload() in loaders, ssr: false, pre-created live query collections, route lifecycle | 3 |
26| custom-adapter | core | Custom Adapter Authoring | SyncConfig, begin/write/commit/markReady, loadSubset, expression parsing | 3 |
27| offline | composition | Offline Transactions | OfflineExecutor, storage adapters, retry, leader election, online detection | 3 |
28
29## Failure Mode Inventory
30
31### Collection Setup & Schema (10 failure modes)
32
33| # | Mistake | Priority | Source | Cross-skill? |
34| --- | ----------------------------------------------------- | -------- | ---------- | ------------ |
35| 1 | queryFn returning empty array deletes all data | CRITICAL | docs | — |
36| 2 | Not knowing which adapter to use | CRITICAL | maintainer | — |
37| 3 | Using async schema validation | HIGH | source | — |
38| 4 | getKey returning undefined | HIGH | source | — |
39| 5 | TInput not superset of TOutput with schema transforms | HIGH | docs | — |
40| 6 | Providing both explicit type param and schema | MEDIUM | docs | — |
41| 7 | React Native missing crypto.randomUUID | HIGH | docs | — |
42| 8 | Electric txid queried outside mutation transaction | CRITICAL | docs | — |
43| 9 | queryFn returning partial data without merging | CRITICAL | docs | — |
44| 10 | Direct writes overridden by next query sync | MEDIUM | docs | — |
45
46### Live Query Construction (8 failure modes)
47
48| # | Mistake | Priority | Source | Cross-skill? |
49| --- | ------------------------------------------------------------ | -------- | ---------- | ------------ |
50| 1 | Using === instead of eq() in where clauses | CRITICAL | source | — |
51| 2 | Filtering/transforming data in JS instead of query operators | CRITICAL | maintainer | — |
52| 3 | Not using the full set of available query operators | HIGH | maintainer | — |
53| 4 | .distinct() without .select() | HIGH | source | — |
54| 5 | .having() without .groupBy() | HIGH | source | — |
55| 6 | .limit()/.offset() without .orderBy() | HIGH | source | — |
56| 7 | Join condition using operator other than eq() | HIGH | source | — |
57| 8 | Passing source directly instead of {alias: collection} | MEDIUM | source | — |
58
59### Framework Integration (4 failure modes)
60
61| # | Mistake | Priority | Source | Cross-skill? |
62| --- | -------------------------------------------- | -------- | ------ | ------------ |
63| 1 | Missing external values in deps array | CRITICAL | docs | — |
64| 2 | Reading Solid signals outside query function | HIGH | docs | — |
65| 3 | useLiveSuspenseQuery without Error Boundary | HIGH | docs | — |
66| 4 | Svelte props not wrapped in getter functions | MEDIUM | docs | — |
67
68### Mutations & Optimistic State (8 failure modes)
69
70| # | Mistake | Priority | Source | Cross-skill? |
71| --- | --------------------------------------------------------------- | -------- | ---------- | ------------ |
72| 1 | Passing object to update() instead of mutating draft | CRITICAL | maintainer | — |
73| 2 | Hallucinating mutation API signatures | CRITICAL | maintainer | — |
74| 3 | onMutate callback returning a Promise | CRITICAL | source | — |
75| 4 | insert/update/delete without handler or ambient transaction | CRITICAL | source | — |
76| 5 | .mutate() after transaction no longer pending | HIGH | source | — |
77| 6 | Attempting to change primary key via update | HIGH | source | — |
78| 7 | Inserting item with duplicate key | HIGH | source | — |
79| 8 | Not awaiting refetch after mutation in query collection handler | HIGH | docs | — |
80
81### Meta-Framework Integration (3 failure modes)
82
83| # | Mistake | Priority | Source | Cross-skill? |
84| --- | -------------------------------------------------------------------- | -------- | -------- | ------------ |
85| 1 | Not preloading collections in route loaders | HIGH | examples | — |
86| 2 | Not setting ssr: false on routes using collections | CRITICAL | examples | — |
87| 3 | Creating new collection instances inside loaders on every navigation | HIGH | docs | — |
88
89### Custom Adapter Authoring (3 failure modes)
90
91| # | Mistake | Priority | Source | Cross-skill? |
92| --- | ----------------------------------------------- | -------- | ------ | ------------ |
93| 1 | Not calling markReady() in sync implementation | CRITICAL | docs | — |
94| 2 | Race condition: subscribing after initial fetch | HIGH | docs | — |
95| 3 | write() called without begin() | HIGH | source | — |
96
97### Offline Transactions (3 failure modes)
98
99| # | Mistake | Priority | Source | Cross-skill? |
100| --- | ----------------------------------------------------- | -------- | ---------- | ------------ |
101| 1 | Using offline transactions when not needed | HIGH | maintainer | — |
102| 2 | Not handling NonRetriableError for permanent failures | HIGH | source | — |
103| 3 | Multiple tabs executing same queued transaction | CRITICAL | source | — |
104
105**Total: 39 failure modes (14 CRITICAL, 19 HIGH, 6 MEDIUM)**
106
107## Key Maintainer Insights (not in docs)
108
1091. **Always prefer query operators over JS** — Live queries are incrementally maintained via D2 differential dataflow. A `.where(eq(...))` only recomputes the delta on data changes, while `.filter()` in JS re-runs from scratch. This applies even for trivial transformations.
110
1112. **The update API is Immer-style** — `collection.update(id, (draft) => { draft.title = "new" })` not `collection.update(id, { ...item, title: "new" })`. This is the single most common mutation API mistake AI agents make.
112
1133. **Agents hallucinate mutation APIs** — The mutation surface has nuance (handler signatures, ambient transaction context, createOptimisticAction vs createTransaction). Agents generate plausible-looking but wrong code.
114
1154. **Collection type selection matters** — Don't default to bare `createCollection` or `localOnlyCollectionOptions`. Each backend has a dedicated adapter that handles sync, handlers, and utilities correctly.
116
1175. **localOnly is a valid prototyping strategy** — `localOnlyCollectionOptions` → real backend adapter is a clean upgrade path.
118
1196. **Offline is hard — only when needed** — Don't steer users toward offline unless they need it. PowerSync/RxDB handle their own local persistence, which is different from offline transaction queuing.
120
1217. **SSR is not supported yet** — Collections are client-side only. Routes using collections must set `ssr: false`. Preloading happens in client-side route loaders, not on the server.
122
1238. **Transactions stack** — Concurrent transactions build optimistic state on top of each other. Use TanStack Pacer for sequential execution when ordering matters.
124
125## Tensions
126
127| Tension | Skills | Agent implication |
128| ---------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
129| Simplicity vs. correctness in sync | collection-setup ↔ custom-adapter | Agents use localOnly or eager mode for everything; production needs adapter-specific patterns |
130| Optimistic speed vs. data consistency | mutations-optimistic ↔ collection-setup | Agents apply optimistic updates without considering rollback UX or awaiting refetch |
131| Query expressiveness vs. IVM constraints | live-queries ↔ framework-integration | Agents write SQL-style queries that violate IVM constraints (equality joins only, orderBy for limit, etc.) |
132| Offline complexity vs. app simplicity | offline ↔ mutations-optimistic | Agents add offline-transactions to apps that only need basic optimistic mutations |
133
134## Cross-References
135
136| From | To | Reason |
137| --------------------- | --------------------- | -------------------------------------------------------------------------- |
138| framework-integration | meta-framework | Hooks render data; loaders preload it. Both needed for production routing. |
139| meta-framework | framework-integration | Preloaded collections consumed by hooks; hook API informs what to preload. |
140| collection-setup | mutations-optimistic | Mutation handlers configured at setup time, execute during mutations. |
141| mutations-optimistic | collection-setup | Handler signatures depend on adapter (Electric txid, Query refetch). |
142| live-queries | collection-setup | Queries reference collections; sync modes affect query behavior. |
143| custom-adapter | collection-setup | Custom adapters produce same CollectionConfig shape as built-in adapters. |
144| offline | mutations-optimistic | Offline wraps the same transaction/mutation model. |
145
146## Subsystems & Reference Candidates
147
148| Skill | Subsystems | Reference candidates |
149| --------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------- |
150| collection-setup | TanStack Query, ElectricSQL, PowerSync, RxDB, TrailBase, local-only, localStorage | Adapter configs with examples |
151| live-queries | — | Query operators (>20 distinct operators with signatures) |
152| framework-integration | React, Vue, Svelte, Solid, Angular | Per-framework hook patterns |
153| mutations-optimistic | — | Transaction API, draft proxy, paced mutations |
154| meta-framework | — | — |
155| custom-adapter | — | SyncConfig contract, expression parsing helpers |
156| offline | — | Storage adapters, retry policies, leader election |
157
158## Remaining Gaps
159
160| Skill | Question | Status |
161| -------------------- | ---------------------------------------------------------------------------------------- | ------ |
162| meta-framework | Patterns for non-TanStack-Start frameworks (Next.js App Router, Remix, Nuxt, SvelteKit)? | open |
163| collection-setup | Collection GC/disposal patterns in route-based SPAs? | open |
164| live-queries | Performance cliffs — at what complexity/data size do queries degrade? | open |
165| mutations-optimistic | Recommended pattern for temporary ID → server ID mapping? | open |
166| meta-framework | Specific TanStack Router integration patterns for prefetching? | open |
167| offline | Behavior of in-flight transactions when browser goes offline mid-persist? | open |
168
169## Recommended Skill File Structure
170
171- **Core skills:** collection-setup, live-queries, mutations-optimistic, custom-adapter
172- **Framework skills:** framework-integration (per-framework references)
173- **Composition skills:** meta-framework, offline
174- **Reference files needed:**
175 - collection-setup: per-adapter config references (7 adapters)
176 - live-queries: operator reference (>20 operators)
177 - framework-integration: per-framework hook references (5 frameworks)
178 - custom-adapter: SyncConfig contract reference
179
180### Monorepo skill placement
181
182| Package | Skills |
183| ------------------------------- | -------------------------------------------------------------------- |
184| `packages/db` | collection-setup, live-queries, mutations-optimistic, custom-adapter |
185| `packages/react-db` | framework-integration (React) |
186| `packages/vue-db` | framework-integration (Vue) |
187| `packages/svelte-db` | framework-integration (Svelte) |
188| `packages/solid-db` | framework-integration (Solid) |
189| `packages/angular-db` | framework-integration (Angular) |
190| `packages/offline-transactions` | offline |
191| Meta-framework | meta-framework (in `packages/db` or repo-level) |
192
193## Composition Opportunities
194
195| Library | Integration points | Composition skill needed? |
196| -------------------------------- | ----------------------------------------------------- | ---------------------------------------- |
197| TanStack Query | queryCollectionOptions wraps QueryObserver | Built into collection-setup adapter refs |
198| TanStack Router | Route loaders for collection preloading | meta-framework skill |
199| TanStack Start | Full-stack framework with ssr: false pattern | meta-framework skill |
200| ElectricSQL | Real-time sync via ShapeStream; txid tracking | Built into collection-setup adapter refs |
201| PowerSync | SQLite offline persistence; diff-trigger changes | Built into collection-setup adapter refs |
202| RxDB | Observable-driven sync; RxJS subscriptions | Built into collection-setup adapter refs |
203| TrailBase | Event stream sync; cursor-based pagination | Built into collection-setup adapter refs |
204| Zod / Valibot / ArkType / Effect | Schema validation via StandardSchema spec | Built into collection-setup |
205| TanStack Table | Virtual table rendering of live query results | Needs investigation |
206| TanStack Pacer | Sequential transaction execution, debounced mutations | Built into mutations-optimistic |