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

createSyncStoragePersister.md

160 lines4.5 KB

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```sh
16npm install @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
17```
18​
19or
20​
21```sh
22pnpm add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
23```
24​
25or
26​
27```sh
28yarn add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
29```
30​
31or
32​
33```sh
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: 24 * 60 * 60 * 1000, // 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
122```
123​
124The default options are:
125​
126```tsx
128 key = `REACT_QUERY_OFFLINE_CACHE`,
129 throttleTime = 1000,
130 serialize = JSON.stringify,
131 deserialize = JSON.parse,
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```