Open History to see the last commit
1---
2id: createSyncStoragePersister
3title: createSyncStoragePersister
4---
5β
6## Deprecated
7β
8This plugin is deprecated and will be removed in the next major version.
9You can simply use ['@tanstack/query-async-storage-persister'](./createAsyncStoragePersister.md) instead.
10β
11## Installation
12β
13This utility comes as a separate package and is available under the `'@tanstack/query-sync-storage-persister'` import.
14β
15```bash
16npm install @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
17```
18β
19or
20β
21```bash
22pnpm add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
23```
24β
25or
26β
27```bash
28yarn add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
29```
30β
31or
32β
33```bash
34bun add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
35```
36β
37## Usage
38β
39- Import the `createSyncStoragePersister` function
40- Create a new syncStoragePersister
41- Pass it to the [`persistQueryClient`](./persistQueryClient.md) function
42β
43```tsx
44import { persistQueryClient } from '@tanstack/react-query-persist-client'
45import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
46β
47const queryClient = new QueryClient({
48 defaultOptions: {
49 queries: {
50 gcTime: 1000 * 60 * 60 * 24, // 24 hours
51 },
52 },
53})
54β
55const localStoragePersister = createSyncStoragePersister({
56 storage: window.localStorage,
57})
58// const sessionStoragePersister = createSyncStoragePersister({ storage: window.sessionStorage })
59β
60persistQueryClient({
61 queryClient,
62 persister: localStoragePersister,
63})
64```
65β
66## Retries
67β
68Persistence can fail, e.g. if the size exceeds the available space on the storage. Errors can be handled gracefully by providing a `retry` function to the persister.
69β
70The retry function receives the `persistedClient` it tried to save, as well as the `error` and the `errorCount` as input. It is expected to return a _new_ `PersistedClient`, with which it tries to persist again. If _undefined_ is returned, there will be no further attempt to persist.
71β
72```tsx
73export type PersistRetryer = (props: {
74 persistedClient: PersistedClient
75 error: Error
76 errorCount: number
77}) => PersistedClient | undefined
78```
79β
80### Predefined strategies
81β
82Per default, no retry will occur. You can use one of the predefined strategies to handle retries. They can be imported `from '@tanstack/react-query-persist-client'`:
83β
84- `removeOldestQuery`
85 - will return a new `PersistedClient` with the oldest query removed.
86β
87```tsx
88const localStoragePersister = createSyncStoragePersister({
89 storage: window.localStorage,
90 retry: removeOldestQuery,
91})
92```
93β
94## API
95β
96### `createSyncStoragePersister`
97β
98Call this function to create a syncStoragePersister that you can use later with `persistQueryClient`.
99β
100```tsx
101createSyncStoragePersister(options: CreateSyncStoragePersisterOptions)
102```
103β
104### `Options`
105β
106```tsx
107interface CreateSyncStoragePersisterOptions {
108 /** The storage client used for setting an retrieving items from cache (window.localStorage or window.sessionStorage) */
109 storage: Storage | undefined | null
110 /** The key to use when storing the cache */
111 key?: string
112 /** To avoid spamming,
113 * pass a time in ms to throttle saving the cache to disk */
114 throttleTime?: number
115 /** How to serialize the data to storage */
116 serialize?: (client: PersistedClient) => string
117 /** How to deserialize the data from storage */
118 deserialize?: (cachedString: string) => PersistedClient
119 /** How to retry persistence on error **/
120 retry?: PersistRetryer
121}
122```
123β
124The default options are:
125β
126```tsx
127{
128 key = `REACT_QUERY_OFFLINE_CACHE`,
129 throttleTime = 1000,
130 serialize = JSON.stringify,
131 deserialize = JSON.parse,
132}
133```
134β
135#### `serialize` and `deserialize` options
136β
137There is a limit to the amount of data which can be stored in `localStorage`.
138If you need to store more data in `localStorage`, you can override the `serialize` and `deserialize` functions to compress and decompress the data using a library like [lz-string](https://github.com/pieroxy/lz-string/).
139β
140```tsx
141import { QueryClient } from '@tanstack/react-query'
142import { persistQueryClient } from '@tanstack/react-query-persist-client'
143import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
144β
145import { compress, decompress } from 'lz-string'
146β
147const queryClient = new QueryClient({
148 defaultOptions: { queries: { staleTime: Infinity } },
149})
150β
151persistQueryClient({
152 queryClient: queryClient,
153 persister: createSyncStoragePersister({
154 storage: window.localStorage,
155 serialize: (data) => compress(JSON.stringify(data)),
156 deserialize: (data) => JSON.parse(decompress(data)),
157 }),
158 maxAge: Infinity,
159})
160```