Open History to see the last commit
1---
2id: createAsyncStoragePersister
3title: createAsyncStoragePersister
4---
5β
6## Installation
7β
8This utility comes as a separate package and is available under the `'@tanstack/query-async-storage-persister'` import.
9β
10```bash
11npm install @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
12```
13β
14or
15β
16```bash
17pnpm add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
18```
19β
20or
21β
22```bash
23yarn add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
24```
25β
26or
27β
28```bash
29bun add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
30```
31β
32## Usage
33β
34- Import the `createAsyncStoragePersister` function
35- Create a new asyncStoragePersister
36 - you can pass any `storage` to it that adheres to the `AsyncStorage` interface - the example below uses the async-storage from React Native
37- Wrap your app by using [`PersistQueryClientProvider`](../persistQueryClient#persistqueryclientprovider) component.
38β
39```tsx
40import AsyncStorage from '@react-native-async-storage/async-storage'
41import { QueryClient } from '@tanstack/react-query'
42import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
43import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
44β
45const queryClient = new QueryClient({
46 defaultOptions: {
47 queries: {
48 gcTime: 1000 * 60 * 60 * 24, // 24 hours
49 },
50 },
51})
52β
53const asyncStoragePersister = createAsyncStoragePersister({
54 storage: AsyncStorage,
55})
56β
57const Root = () => (
58 <PersistQueryClientProvider
59 client={queryClient}
60 persistOptions={{ persister: asyncStoragePersister }}
61 >
62 <App />
63 </PersistQueryClientProvider>
64)
65β
66export default Root
67```
68β
69## Retries
70β
71Retries work the same as for a [SyncStoragePersister](../createSyncStoragePersister), except that they can also be asynchronous. You can also use all the predefined retry handlers.
72β
73## API
74β
75### `createAsyncStoragePersister`
76β
77Call this function to create an asyncStoragePersister that you can use later with `persistQueryClient`.
78β
79```tsx
80createAsyncStoragePersister(options: CreateAsyncStoragePersisterOptions)
81```
82β
83### `Options`
84β
85```tsx
86interface CreateAsyncStoragePersisterOptions {
87 /** The storage client used for setting an retrieving items from cache */
88 storage: AsyncStorage | undefined | null
89 /** The key to use when storing the cache to localStorage */
90 key?: string
91 /** To avoid localStorage spamming,
92 * pass a time in ms to throttle saving the cache to disk */
93 throttleTime?: number
94 /** How to serialize the data to storage */
95 serialize?: (client: PersistedClient) => string
96 /** How to deserialize the data from storage */
97 deserialize?: (cachedString: string) => PersistedClient
98 /** How to retry persistence on error **/
99 retry?: AsyncPersistRetryer
100}
101β
102interface AsyncStorage {
103 getItem: (key: string) => Promise<string | null>
104 setItem: (key: string, value: string) => Promise<unknown>
105 removeItem: (key: string) => Promise<void>
106}
107```
108β
109The default options are:
110β
111```tsx
112{
113 key = `REACT_QUERY_OFFLINE_CACHE`,
114 throttleTime = 1000,
115 serialize = JSON.stringify,
116 deserialize = JSON.parse,
117}
118```