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

createAsyncStoragePersister.md

122 lines3.5 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```sh
11npm install @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
12```
13​
14or
15​
16```sh
17pnpm add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
18```
19​
20or
21​
22```sh
23yarn add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
24```
25​
26or
27​
28```sh
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 - storages that read and write synchronously, like `window.localstorage`, also adhere to the `AsyncStorage` interface and can therefore also be used with `createAsyncStoragePersister`.
38- Wrap your app by using [`PersistQueryClientProvider`](./persistQueryClient.md#persistqueryclientprovider) component.
39​
40```tsx
41import AsyncStorage from '@react-native-async-storage/async-storage'
42import { QueryClient } from '@tanstack/react-query'
43import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
44import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
45​
46const queryClient = new QueryClient({
47 defaultOptions: {
48 queries: {
49 gcTime: 24 * 60 * 60 * 1000, // 24 hours
50 },
51 },
52})
53​
54const asyncStoragePersister = createAsyncStoragePersister({
55 storage: AsyncStorage,
56})
57​
58const Root = () => (
59 <PersistQueryClientProvider
60 client={queryClient}
61 persistOptions={{ persister: asyncStoragePersister }}
62 >
63 <App />
64 </PersistQueryClientProvider>
66​
67export default Root
68```
69​
70## Retries
71​
72Retries 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.
73​
74## API
75​
76### `createAsyncStoragePersister`
77​
78Call this function to create an asyncStoragePersister that you can use later with `persistQueryClient`.
79​
80```tsx
81createAsyncStoragePersister(options: CreateAsyncStoragePersisterOptions)
82```
83​
84### `Options`
85​
86```tsx
87interface CreateAsyncStoragePersisterOptions {
88 /** The storage client used for setting an retrieving items from cache */
89 storage: AsyncStorage | undefined | null
90 /** The key to use when storing the cache to localStorage */
91 key?: string
92 /** To avoid localStorage spamming,
93 * pass a time in ms to throttle saving the cache to disk */
94 throttleTime?: number
95 /** How to serialize the data to storage */
96 serialize?: (client: PersistedClient) => MaybePromise<string>
97 /** How to deserialize the data from storage */
98 deserialize?: (cachedString: string) => MaybePromise<PersistedClient>
99 /** How to retry persistence on error **/
100 retry?: AsyncPersistRetryer
102​
103interface AsyncStorage<TStorageValue = string> {
104 getItem: (key: string) => MaybePromise<TStorageValue | undefined | null>
105 setItem: (key: string, value: TStorageValue) => MaybePromise<unknown>
106 removeItem: (key: string) => MaybePromise<void>
107 entries?: () => MaybePromise<Array<[key: string, value: TStorageValue]>>
109```
110​
111The `serialize` and `deserialize` callbacks can return their results synchronously or asynchronously as promises.
112​
113The default options are:
114​
115```tsx
117 key = `REACT_QUERY_OFFLINE_CACHE`,
118 throttleTime = 1000,
119 serialize = JSON.stringify,
120 deserialize = JSON.parse,
122```