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

localStorageCollectionOptions.md

236 lines6.8 KB

1---
2id: localStorageCollectionOptions
3title: localStorageCollectionOptions
4---
5​
6# Function: localStorageCollectionOptions()
7​
8## Call Signature
9​
10```ts
11function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, LocalStorageCollectionUtils> & object;
12```
13​
14Defined in: [packages/db/src/local-storage.ts:316](https://github.com/TanStack/db/blob/main/packages/db/src/local-storage.ts#L316)
15​
16Creates localStorage collection options for use with a standard Collection
17​
18This function creates a collection that persists data to localStorage/sessionStorage
19and synchronizes changes across browser tabs using storage events.
20​
21**Fallback Behavior:**
22​
23When localStorage is not available (e.g., in server-side rendering environments),
24this function automatically falls back to an in-memory storage implementation.
25This prevents errors during module initialization and allows the collection to
26work in any environment, though data will not persist across page reloads or
27be shared across tabs when using the in-memory fallback.
28​
29**Using with Manual Transactions:**
30​
31For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
32to persist changes made during `tx.mutate()`. This is necessary because local-storage collections
33don't participate in the standard mutation handler flow for manual transactions.
34​
35### Type Parameters
36​
37#### T
38​
39`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
40​
41#### TKey
42​
43`TKey` *extends* `string` \| `number` = `string` \| `number`
44​
45### Parameters
46​
47#### config
48​
49[`LocalStorageCollectionConfig`](../interfaces/LocalStorageCollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `T`, `TKey`\> & `object`
50​
51Configuration options for the localStorage collection
52​
53### Returns
54​
55[`CollectionConfig`](../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, [`LocalStorageCollectionUtils`](../interfaces/LocalStorageCollectionUtils.md)\> & `object`
56​
57Collection options with utilities including clearStorage, getStorageSize, and acceptMutations
58​
59### Examples
60​
61```ts
62// Basic localStorage collection
63const collection = createCollection(
64 localStorageCollectionOptions({
65 storageKey: 'todos',
66 getKey: (item) => item.id,
67 })
69```
70​
71```ts
72// localStorage collection with custom storage
73const collection = createCollection(
74 localStorageCollectionOptions({
75 storageKey: 'todos',
76 storage: window.sessionStorage, // Use sessionStorage instead
77 getKey: (item) => item.id,
78 })
80```
81​
82```ts
83// localStorage collection with mutation handlers
84const collection = createCollection(
85 localStorageCollectionOptions({
86 storageKey: 'todos',
87 getKey: (item) => item.id,
88 onInsert: async ({ transaction }) => {
89 console.log('Item inserted:', transaction.mutations[0].modified)
90 },
91 })
93```
94​
95```ts
96// Using with manual transactions
97const localSettings = createCollection(
98 localStorageCollectionOptions({
99 storageKey: 'user-settings',
100 getKey: (item) => item.id,
101 })
103​
104const tx = createTransaction({
105 mutationFn: async ({ transaction }) => {
106 // Use settings data in API call
107 const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)
108 await api.updateUserProfile({ settings: settingsMutations[0]?.modified })
109​
110 // Persist local-storage mutations after API success
111 localSettings.utils.acceptMutations(transaction)
112 }
113})
114​
115tx.mutate(() => {
116 localSettings.insert({ id: 'theme', value: 'dark' })
117 apiCollection.insert({ id: 2, data: 'profile data' })
118})
119​
120await tx.commit()
121```
122​
123## Call Signature
124​
125```ts
126function localStorageCollectionOptions<T, TKey>(config): CollectionConfig<T, TKey, never, LocalStorageCollectionUtils> & object;
127```
128​
129Defined in: [packages/db/src/local-storage.ts:336](https://github.com/TanStack/db/blob/main/packages/db/src/local-storage.ts#L336)
130​
131Creates localStorage collection options for use with a standard Collection
132​
133This function creates a collection that persists data to localStorage/sessionStorage
134and synchronizes changes across browser tabs using storage events.
135​
136**Fallback Behavior:**
137​
138When localStorage is not available (e.g., in server-side rendering environments),
139this function automatically falls back to an in-memory storage implementation.
140This prevents errors during module initialization and allows the collection to
141work in any environment, though data will not persist across page reloads or
142be shared across tabs when using the in-memory fallback.
143​
144**Using with Manual Transactions:**
145​
146For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
147to persist changes made during `tx.mutate()`. This is necessary because local-storage collections
148don't participate in the standard mutation handler flow for manual transactions.
149​
150### Type Parameters
151​
152#### T
153​
154`T` *extends* `object`
155​
156#### TKey
157​
158`TKey` *extends* `string` \| `number` = `string` \| `number`
159​
160### Parameters
161​
162#### config
163​
164[`LocalStorageCollectionConfig`](../interfaces/LocalStorageCollectionConfig.md)\<`T`, `never`, `TKey`\> & `object`
165​
166Configuration options for the localStorage collection
167​
168### Returns
169​
170[`CollectionConfig`](../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, [`LocalStorageCollectionUtils`](../interfaces/LocalStorageCollectionUtils.md)\> & `object`
171​
172Collection options with utilities including clearStorage, getStorageSize, and acceptMutations
173​
174### Examples
175​
176```ts
177// Basic localStorage collection
178const collection = createCollection(
179 localStorageCollectionOptions({
180 storageKey: 'todos',
181 getKey: (item) => item.id,
182 })
184```
185​
186```ts
187// localStorage collection with custom storage
188const collection = createCollection(
189 localStorageCollectionOptions({
190 storageKey: 'todos',
191 storage: window.sessionStorage, // Use sessionStorage instead
192 getKey: (item) => item.id,
193 })
195```
196​
197```ts
198// localStorage collection with mutation handlers
199const collection = createCollection(
200 localStorageCollectionOptions({
201 storageKey: 'todos',
202 getKey: (item) => item.id,
203 onInsert: async ({ transaction }) => {
204 console.log('Item inserted:', transaction.mutations[0].modified)
205 },
206 })
208```
209​
210```ts
211// Using with manual transactions
212const localSettings = createCollection(
213 localStorageCollectionOptions({
214 storageKey: 'user-settings',
215 getKey: (item) => item.id,
216 })
218​
219const tx = createTransaction({
220 mutationFn: async ({ transaction }) => {
221 // Use settings data in API call
222 const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)
223 await api.updateUserProfile({ settings: settingsMutations[0]?.modified })
224​
225 // Persist local-storage mutations after API success
226 localSettings.utils.acceptMutations(transaction)
227 }
228})
229​
230tx.mutate(() => {
231 localSettings.insert({ id: 'theme', value: 'dark' })
232 apiCollection.insert({ id: 2, data: 'profile data' })
233})
234​
235await tx.commit()
236```