@@ -11,15 +11,15 @@ Collections are typed data stores that decouple data loading from data binding.
1111
1212## Collection Types
1313
14- | Type | Package | Use Case |
15- | --------------------- | ---------------------------------- | - ------------------------------------ |
16- | ** QueryCollection** | ` @tanstack/query-db-collection ` | REST APIs via TanStack Query |
17- | ** ElectricCollection** | ` @tanstack/electric-db-collection ` | Real-time Postgres sync via Electric |
18- | ** PowerSyncCollection** | ` @tanstack/powersync-db-collection ` | Offline-first with PowerSync |
19- | ** RxDBCollection** | ` @tanstack/rxdb-db-collection ` | RxDB local persistence |
20- | ** TrailBaseCollection** | ` @tanstack/trailbase-db-collection ` | TrailBase real-time backend |
21- | ** LocalStorageCollection** | ` @tanstack/db ` | Browser localStorage persistence |
22- | ** LocalOnlyCollection** | ` @tanstack/db ` | In-memory state (no persistence) |
14+ | Type | Package | Use Case |
15+ | -------------------------- | ----------------------------------- | ------------------------------------ |
16+ | ** QueryCollection** | ` @tanstack/query-db-collection ` | REST APIs via TanStack Query |
17+ | ** ElectricCollection** | ` @tanstack/electric-db-collection ` | Real-time Postgres sync via Electric |
18+ | ** PowerSyncCollection** | ` @tanstack/powersync-db-collection ` | Offline-first with PowerSync |
19+ | ** RxDBCollection** | ` @tanstack/rxdb-db-collection ` | RxDB local persistence |
20+ | ** TrailBaseCollection** | ` @tanstack/trailbase-db-collection ` | TrailBase real-time backend |
21+ | ** LocalStorageCollection** | ` @tanstack/db ` | Browser localStorage persistence |
22+ | ** LocalOnlyCollection** | ` @tanstack/db ` | In-memory state (no persistence) |
2323
2424## Common Patterns
2525
@@ -45,8 +45,8 @@ const todoCollection = createCollection(
4545 fetch (' /api/todos' , {
4646 method: ' POST' ,
4747 body: JSON .stringify (m .modified ),
48- })
49- )
48+ }),
49+ ),
5050 )
5151 },
5252
@@ -56,19 +56,19 @@ const todoCollection = createCollection(
5656 fetch (` /api/todos/${m .original .id } ` , {
5757 method: ' PUT' ,
5858 body: JSON .stringify (m .modified ),
59- })
60- )
59+ }),
60+ ),
6161 )
6262 },
6363
6464 onDelete : async ({ transaction }) => {
6565 await Promise .all (
6666 transaction .mutations .map ((m ) =>
67- fetch (` /api/todos/${m .original .id } ` , { method: ' DELETE' })
68- )
67+ fetch (` /api/todos/${m .original .id } ` , { method: ' DELETE' }),
68+ ),
6969 )
7070 },
71- })
71+ }),
7272)
7373```
7474
@@ -88,18 +88,18 @@ const productsCollection = createCollection(
8888 getKey : (item ) => item .id ,
8989
9090 // Choose sync mode:
91- syncMode: ' eager' , // Default: Load all upfront (<10k rows)
91+ syncMode: ' eager' , // Default: Load all upfront (<10k rows)
9292 // syncMode: 'on-demand', // Load only what queries request (>50k rows)
9393 // syncMode: 'progressive', // Load subset first, sync full in background
94- })
94+ }),
9595)
9696```
9797
98- | Mode | Behavior | Best For |
99- | --------------- | ------------------------------------------- | ---- --------------------------------------- |
100- | ` eager ` | Load entire collection upfront | <10k rows, mostly static data |
101- | ` on-demand ` | Load only what queries request | >50k rows, search interfaces, catalogs |
102- | ` progressive ` | Load query subset, sync full in background | Collaborative apps, instant first paint |
98+ | Mode | Behavior | Best For |
99+ | ------------- | ------------------------------------------ | --------------------------------------- |
100+ | ` eager ` | Load entire collection upfront | <10k rows, mostly static data |
101+ | ` on-demand ` | Load only what queries request | >50k rows, search interfaces, catalogs |
102+ | ` progressive ` | Load query subset, sync full in background | Collaborative apps, instant first paint |
103103
104104### ElectricCollection (Real-time Sync)
105105
@@ -128,22 +128,25 @@ const todoCollection = createCollection(
128128 const response = await api .todos .update (original .id , changes )
129129 return { txid: response .txid }
130130 },
131- })
131+ }),
132132)
133133```
134134
135135### LocalStorageCollection
136136
137137``` tsx
138- import { createCollection , localStorageCollectionOptions } from ' @tanstack/react-db'
138+ import {
139+ createCollection ,
140+ localStorageCollectionOptions ,
141+ } from ' @tanstack/react-db'
139142
140143const settingsCollection = createCollection (
141144 localStorageCollectionOptions ({
142145 id: ' user-settings' ,
143146 storageKey: ' app-settings' ,
144147 getKey : (item ) => item .id ,
145148 schema: settingsSchema ,
146- })
149+ }),
147150)
148151
149152// Data persists across sessions and syncs across tabs
@@ -153,13 +156,16 @@ settingsCollection.insert({ id: 'theme', value: 'dark' })
153156### LocalOnlyCollection
154157
155158``` tsx
156- import { createCollection , localOnlyCollectionOptions } from ' @tanstack/react-db'
159+ import {
160+ createCollection ,
161+ localOnlyCollectionOptions ,
162+ } from ' @tanstack/react-db'
157163
158164const uiStateCollection = createCollection (
159165 localOnlyCollectionOptions ({
160166 id: ' ui-state' ,
161167 getKey : (item ) => item .id ,
162- })
168+ }),
163169)
164170
165171// In-memory only, lost on refresh
@@ -175,8 +181,9 @@ const todoSchema = z.object({
175181 id: z .string (),
176182 text: z .string ().min (1 ),
177183 completed: z .boolean ().default (false ),
178- created_at: z .union ([z .string (), z .date ()])
179- .transform (val => typeof val === ' string' ? new Date (val ) : val )
184+ created_at: z
185+ .union ([z .string (), z .date ()])
186+ .transform ((val ) => (typeof val === ' string' ? new Date (val ) : val ))
180187 .default (() => new Date ()),
181188})
182189
@@ -186,7 +193,7 @@ const todoCollection = createCollection(
186193 queryKey: [' todos' ],
187194 queryFn : async () => api .todos .getAll (),
188195 getKey : (item ) => item .id ,
189- })
196+ }),
190197)
191198```
192199
@@ -203,27 +210,27 @@ const todoCollection = createCollection(
203210 queryFn : async () => api .todos .getAll (),
204211 getKey : (item ) => item .id ,
205212 queryClient , // Use your existing query client
206- })
213+ }),
207214)
208215```
209216
210217## Collection API
211218
212219``` tsx
213220// Read operations
214- collection .get (key ) // Get item by key
215- collection .has (key ) // Check if key exists
216- collection .toArray // Get all items as array
217- collection .size // Number of items
221+ collection .get (key ) // Get item by key
222+ collection .has (key ) // Check if key exists
223+ collection .toArray // Get all items as array
224+ collection .size // Number of items
218225
219226// Write operations (trigger handlers)
220- collection .insert (item ) // Insert item(s)
221- collection .update (key , fn ) // Update item(s) with draft function
222- collection .delete (key ) // Delete item(s)
227+ collection .insert (item ) // Insert item(s)
228+ collection .update (key , fn ) // Update item(s) with draft function
229+ collection .delete (key ) // Delete item(s)
223230
224231// Utilities (collection-specific)
225- collection .utils .refetch () // QueryCollection: refetch from API
226- collection .utils .awaitTxId () // ElectricCollection: wait for txid
232+ collection .utils .refetch () // QueryCollection: refetch from API
233+ collection .utils .awaitTxId () // ElectricCollection: wait for txid
227234collection .utils .awaitMatch () // ElectricCollection: wait for custom match
228235collection .utils .acceptMutations () // LocalCollection: accept in manual tx
229236```
@@ -232,9 +239,9 @@ collection.utils.acceptMutations() // LocalCollection: accept in manual tx
232239
233240``` tsx
234241interface CollectionOptions {
235- id? : string // Unique identifier
236- getKey: (item ) => Key // Extract unique key from item
237- schema? : StandardSchema // Validation schema (Zod, Valibot, etc.)
242+ id? : string // Unique identifier
243+ getKey: (item ) => Key // Extract unique key from item
244+ schema? : StandardSchema // Validation schema (Zod, Valibot, etc.)
238245
239246 // Persistence handlers
240247 onInsert? : MutationFn
@@ -254,10 +261,10 @@ interface CollectionOptions {
254261
255262## Detailed References
256263
257- | Reference | When to Use |
258- | -------------------------------- | ---- ------------------------------------------------ |
259- | ` references/query-collection.md ` | REST API integration, predicate push-down, delta |
260- | ` references/electric-collection.md ` | Electric setup, txid matching, shapes |
261- | ` references/local-collections.md ` | LocalStorage, LocalOnly, cross-tab sync |
262- | ` references/sync-modes.md ` | Eager vs on-demand vs progressive tradeoffs |
263- | ` references/custom-collections.md ` | Building your own collection type |
264+ | Reference | When to Use |
265+ | ----------------------------------- | ------------------------------------------------ |
266+ | ` references/query-collection.md ` | REST API integration, predicate push-down, delta |
267+ | ` references/electric-collection.md ` | Electric setup, txid matching, shapes |
268+ | ` references/local-collections.md ` | LocalStorage, LocalOnly, cross-tab sync |
269+ | ` references/sync-modes.md ` | Eager vs on-demand vs progressive tradeoffs |
270+ | ` references/custom-collections.md ` | Building your own collection type |
0 commit comments