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

localStorageCollectionOptions.md

234 lines6.8 KB

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