📄 tanstack/query/latest/docs/framework/react/plugins/createAsyncStoragePersister

npm install @tanstack/query-async-storage-persister @tanstack/react-query-persist-client


npm install @tanstack/query-async-storage-persister @tanstack/react-query-persist-client

bash

pnpm add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client


pnpm add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client

bash

yarn add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client


yarn add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client

bash

bun add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client


bun add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client

Usage
-----

Import the createAsyncStoragePersister function
Create a new asyncStoragePersister
- you can pass any storage to it that adheres to the AsyncStorage interface - the example below uses the async-storage from React Native.
- storages that read and write synchronously, like window.localstorage, also adhere to the AsyncStorage interface and can therefore also be used with createAsyncStoragePersister.
Wrap your app by using PersistQueryClientProvider component.

tsx

import AsyncStorage from '@react-native-async-storage/async-storage'
import { QueryClient } from '@tanstack/react-query'
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

const asyncStoragePersister = createAsyncStoragePersister({
  storage: AsyncStorage,
})

const Root = () => (
  <PersistQueryClientProvider
    client={queryClient}
    persistOptions={{ persister: asyncStoragePersister }}
  >
    <App />
  </PersistQueryClientProvider>
)

export default Root


import AsyncStorage from '@react-native-async-storage/async-storage'
import { QueryClient } from '@tanstack/react-query'
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

const asyncStoragePersister = createAsyncStoragePersister({
  storage: AsyncStorage,
})

const Root = () => (
  <PersistQueryClientProvider
    client={queryClient}
    persistOptions={{ persister: asyncStoragePersister }}
  >
    <App />
  </PersistQueryClientProvider>
)

export default Root

Retries
-------

Retries work the same as for a SyncStoragePersister , except that they can also be asynchronous. You can also use all the predefined retry handlers.

API
--- ### createAsyncStoragePersister

Call this function to create an asyncStoragePersister that you can use later with persistQueryClient.

tsx

createAsyncStoragePersister(options: CreateAsyncStoragePersisterOptions)


createAsyncStoragePersister(options: CreateAsyncStoragePersisterOptions)

### Options

tsx

interface CreateAsyncStoragePersisterOptions {
  /** The storage client used for setting an retrieving items from cache */
  storage: AsyncStorage | undefined | null
  /** The key to use when storing the cache to localStorage */
  key?: string
  /** To avoid localStorage spamming,
   * pass a time in ms to throttle saving the cache to disk */
  throttleTime?: number
  /** How to serialize the data to storage */
  serialize?: (client: PersistedClient) => string
  /** How to deserialize the data from storage */
  deserialize?: (cachedString: string) => PersistedClient
  /** How to retry persistence on error **/
  retry?: AsyncPersistRetryer
}

interface AsyncStorage<TStorageValue = string> {
  getItem: (key: string) => MaybePromise<TStorageValue | undefined | null>
  setItem: (key: string, value: TStorageValue) => MaybePromise<unknown>
  removeItem: (key: string) => MaybePromise<void>
  entries?: () => MaybePromise<Array<[key: string, value: TStorageValue]>>
}


interface CreateAsyncStoragePersisterOptions {
  /** The storage client used for setting an retrieving items from cache */
  storage: AsyncStorage | undefined | null
  /** The key to use when storing the cache to localStorage */
  key?: string
  /** To avoid localStorage spamming,
   * pass a time in ms to throttle saving the cache to disk */
  throttleTime?: number
  /** How to serialize the data to storage */
  serialize?: (client: PersistedClient) => string
  /** How to deserialize the data from storage */
  deserialize?: (cachedString: string) => PersistedClient
  /** How to retry persistence on error **/
  retry?: AsyncPersistRetryer
}

interface AsyncStorage<TStorageValue = string> {
  getItem: (key: string) => MaybePromise<TStorageValue | undefined | null>
  setItem: (key: string, value: TStorageValue) => MaybePromise<unknown>
  removeItem: (key: string) => MaybePromise<void>
  entries?: () => MaybePromise<Array<[key: string, value: TStorageValue]>>
}

The default options are:

tsx

{
  key = `REACT_QUERY_OFFLINE_CACHE`,
  throttleTime = 1000,
  serialize = JSON.stringify,
  deserialize = JSON.parse,
}


{
  key = `REACT_QUERY_OFFLINE_CACHE`,
  throttleTime = 1000,
  serialize = JSON.stringify,
  deserialize = JSON.parse,
}

Edit on GitHub

createSyncStoragePersister

broadcastQueryClient (Experimental)

Partners Become a Partner

[###### Want to Skip the Docs?

Query.gg - The Official React Query Course
\

“If you’re serious about *really* understanding React Query, there’s no better way than with query.gg”—Tanner Linsley

Learn More](https://query.gg/?s=tanstack)

scarf analytics