Open History to see the last commit
1---
2id: localOnlyCollectionOptions
3title: localOnlyCollectionOptions
4---
5
6# Function: localOnlyCollectionOptions()
7
8## Call Signature
9
10```ts
11function localOnlyCollectionOptions<T, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, LocalOnlyCollectionUtils> & object & object;
12```
13
14Defined in: [packages/db/src/local-only.ts:149](https://github.com/TanStack/db/blob/main/packages/db/src/local-only.ts#L149)
15
16Creates Local-only collection options for use with a standard Collection
17
18This is an in-memory collection that doesn't sync with external sources but uses a loopback sync config
19that immediately "syncs" all optimistic changes to the collection, making them permanent.
20Perfect for local-only data that doesn't need persistence or external synchronization.
21
22**Using with Manual Transactions:**
23
24For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
25to persist changes made during `tx.mutate()`. This is necessary because local-only collections
26don't participate in the standard mutation handler flow for manual transactions.
27
28### Type Parameters
29
30#### T
31
32`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
33
34The schema type if a schema is provided, otherwise the type of items in the collection
35
36#### TKey
37
38`TKey` *extends* `string` \| `number` = `string` \| `number`
39
40The type of the key returned by getKey
41
42### Parameters
43
44#### config
45
46[`LocalOnlyCollectionConfig`](../interfaces/LocalOnlyCollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `T`, `TKey`\> & `object`
47
48Configuration options for the Local-only collection
49
50### Returns
51
52[`CollectionConfig`](../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, [`LocalOnlyCollectionUtils`](../interfaces/LocalOnlyCollectionUtils.md)\> & `object` & `object`
53
54Collection options with utilities including acceptMutations
55
56### Examples
57
58```ts
59// Basic local-only collection
60const collection = createCollection(
61 localOnlyCollectionOptions({
62 getKey: (item) => item.id,
63 })
64)
65```
66
67```ts
68// Local-only collection with initial data
69const collection = createCollection(
70 localOnlyCollectionOptions({
71 getKey: (item) => item.id,
72 initialData: [
73 { id: 1, name: 'Item 1' },
74 { id: 2, name: 'Item 2' },
75 ],
76 })
77)
78```
79
80```ts
81// Local-only collection with mutation handlers
82const collection = createCollection(
83 localOnlyCollectionOptions({
84 getKey: (item) => item.id,
85 onInsert: async ({ transaction }) => {
86 console.log('Item inserted:', transaction.mutations[0].modified)
87 // Custom logic after insert
88 },
89 })
90)
91```
92
93```ts
94// Using with manual transactions
95const localData = createCollection(
96 localOnlyCollectionOptions({
97 getKey: (item) => item.id,
98 })
99)
100
101const tx = createTransaction({
102 mutationFn: async ({ transaction }) => {
103 // Use local data in API call
104 const localMutations = transaction.mutations.filter(m => m.collection === localData)
105 await api.save({ metadata: localMutations[0]?.modified })
106
107 // Persist local-only mutations after API success
108 localData.utils.acceptMutations(transaction)
109 }
110})
111
112tx.mutate(() => {
113 localData.insert({ id: 1, data: 'metadata' })
114 apiCollection.insert({ id: 2, data: 'main data' })
115})
116
117await tx.commit()
118```
119
120## Call Signature
121
122```ts
123function localOnlyCollectionOptions<T, TKey>(config): CollectionConfig<T, TKey, never, LocalOnlyCollectionUtils> & object & object;
124```
125
126Defined in: [packages/db/src/local-only.ts:162](https://github.com/TanStack/db/blob/main/packages/db/src/local-only.ts#L162)
127
128Creates Local-only collection options for use with a standard Collection
129
130This is an in-memory collection that doesn't sync with external sources but uses a loopback sync config
131that immediately "syncs" all optimistic changes to the collection, making them permanent.
132Perfect for local-only data that doesn't need persistence or external synchronization.
133
134**Using with Manual Transactions:**
135
136For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
137to persist changes made during `tx.mutate()`. This is necessary because local-only collections
138don't participate in the standard mutation handler flow for manual transactions.
139
140### Type Parameters
141
142#### T
143
144`T` *extends* `object`
145
146The schema type if a schema is provided, otherwise the type of items in the collection
147
148#### TKey
149
150`TKey` *extends* `string` \| `number` = `string` \| `number`
151
152The type of the key returned by getKey
153
154### Parameters
155
156#### config
157
158[`LocalOnlyCollectionConfig`](../interfaces/LocalOnlyCollectionConfig.md)\<`T`, `never`, `TKey`\> & `object`
159
160Configuration options for the Local-only collection
161
162### Returns
163
164[`CollectionConfig`](../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, [`LocalOnlyCollectionUtils`](../interfaces/LocalOnlyCollectionUtils.md)\> & `object` & `object`
165
166Collection options with utilities including acceptMutations
167
168### Examples
169
170```ts
171// Basic local-only collection
172const collection = createCollection(
173 localOnlyCollectionOptions({
174 getKey: (item) => item.id,
175 })
176)
177```
178
179```ts
180// Local-only collection with initial data
181const collection = createCollection(
182 localOnlyCollectionOptions({
183 getKey: (item) => item.id,
184 initialData: [
185 { id: 1, name: 'Item 1' },
186 { id: 2, name: 'Item 2' },
187 ],
188 })
189)
190```
191
192```ts
193// Local-only collection with mutation handlers
194const collection = createCollection(
195 localOnlyCollectionOptions({
196 getKey: (item) => item.id,
197 onInsert: async ({ transaction }) => {
198 console.log('Item inserted:', transaction.mutations[0].modified)
199 // Custom logic after insert
200 },
201 })
202)
203```
204
205```ts
206// Using with manual transactions
207const localData = createCollection(
208 localOnlyCollectionOptions({
209 getKey: (item) => item.id,
210 })
211)
212
213const tx = createTransaction({
214 mutationFn: async ({ transaction }) => {
215 // Use local data in API call
216 const localMutations = transaction.mutations.filter(m => m.collection === localData)
217 await api.save({ metadata: localMutations[0]?.modified })
218
219 // Persist local-only mutations after API success
220 localData.utils.acceptMutations(transaction)
221 }
222})
223
224tx.mutate(() => {
225 localData.insert({ id: 1, data: 'metadata' })
226 apiCollection.insert({ id: 2, data: 'main data' })
227})
228
229await tx.commit()
230```