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

createAsyncStoragePersister.md

118 lines3.1 KB

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.md#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>
65​
66export default Root
67```
68​
69## Retries
70​
71Retries work the same as for a [SyncStoragePersister](./createSyncStoragePersister.md), 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
101​
102interface AsyncStorage {
103 getItem: (key: string) => Promise<string | null>
104 setItem: (key: string, value: string) => Promise<unknown>
105 removeItem: (key: string) => Promise<void>
107```
108​
109The default options are:
110​
111```tsx
113 key = `REACT_QUERY_OFFLINE_CACHE`,
114 throttleTime = 1000,
115 serialize = JSON.stringify,
116 deserialize = JSON.parse,
118```