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

createAsyncStoragePersister.md

112 lines3.0 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​
26## Usage
27​
28- Import the `createAsyncStoragePersister` function
29- Create a new asyncStoragePersister
30 - you can pass any `storage` to it that adheres to the `AsyncStorage` interface - the example below uses the async-storage from React Native
31- Wrap your app by using [`PersistQueryClientProvider`](../persistQueryClient#persistqueryclientprovider) component.
32​
33```tsx
34import AsyncStorage from '@react-native-async-storage/async-storage'
35import { QueryClient } from '@tanstack/react-query'
36import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
37import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
38​
39const queryClient = new QueryClient({
40 defaultOptions: {
41 queries: {
42 cacheTime: 1000 * 60 * 60 * 24, // 24 hours
43 },
44 },
45})
46​
47const asyncStoragePersister = createAsyncStoragePersister({
48 storage: AsyncStorage,
49})
50​
51const Root = () => (
52 <PersistQueryClientProvider
53 client={queryClient}
54 persistOptions={{ persister: asyncStoragePersister }}
55 >
56 <App />
57 </PersistQueryClientProvider>
59​
60export default Root
61```
62​
63## Retries
64​
65Retries work the same as for a [SyncStoragePersister](../createSyncStoragePersister), except that they can also be asynchronous. You can also use all the predefined retry handlers.
66​
67## API
68​
69### `createAsyncStoragePersister`
70​
71Call this function to create an asyncStoragePersister that you can use later with `persistQueryClient`.
72​
73```tsx
74createAsyncStoragePersister(options: CreateAsyncStoragePersisterOptions)
75```
76​
77### `Options`
78​
79```tsx
80interface CreateAsyncStoragePersisterOptions {
81 /** The storage client used for setting an retrieving items from cache */
82 storage: AsyncStorage | undefined | null
83 /** The key to use when storing the cache to localStorage */
84 key?: string
85 /** To avoid localStorage spamming,
86 * pass a time in ms to throttle saving the cache to disk */
87 throttleTime?: number
88 /** How to serialize the data to storage */
89 serialize?: (client: PersistedClient) => string
90 /** How to deserialize the data from storage */
91 deserialize?: (cachedString: string) => PersistedClient
92 /** How to retry persistence on error **/
93 retry?: AsyncPersistRetryer
95​
96interface AsyncStorage {
97 getItem: (key: string) => Promise<string | null>
98 setItem: (key: string, value: string) => Promise<unknown>
99 removeItem: (key: string) => Promise<void>
101```
102​
103The default options are:
104​
105```tsx
107 key = `REACT_QUERY_OFFLINE_CACHE`,
108 throttleTime = 1000,
109 serialize = JSON.stringify,
110 deserialize = JSON.parse,
112```