Skip to main content

createAsyncStoragePersister

Installation​

This utility comes as a separate package and is available under the '@tanstack/query-async-storage-persister' import.

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

or

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

or

yarn 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
  • Wrap your app by using PersistQueryClientProvider component.
import AsyncStorage from "@react-native-async-storage/async-storage";
import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
import { createAsyncStoragePersister } from "@tanstack/query-async-storage-persister";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      cacheTime: 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.

createAsyncStoragePersister(options: CreateAsyncStoragePersisterOptions)

Options​

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 {
  getItem: (key: string) => Promise<string | null>;
  setItem: (key: string, value: string) => Promise<unknown>;
  removeItem: (key: string) => Promise<void>;
}

The default options are:

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