createSyncStoragePersister
Installation
This utility comes as a separate package and is available under the '@tanstack/query-sync-storage-persister' import.
1npm install @tanstack/query-sync-storage-persister @tanstack/react-query-persist-clientor
1pnpm add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-clientor
1yarn add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-clientUsage
- Import the
createSyncStoragePersisterfunction - Create a new syncStoragePersister
- Pass it to the
persistQueryClientfunction
1import { persistQueryClient } from "@tanstack/react-query-persist-client";2import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister";3 4const queryClient = new QueryClient({5 defaultOptions: {6 queries: {7 cacheTime: 1000 * 60 * 60 * 24, // 24 hours8 },9 },10});11 12const localStoragePersister = createSyncStoragePersister({13 storage: window.localStorage,14});15// const sessionStoragePersister = createSyncStoragePersister({ storage: window.sessionStorage })16 17persistQueryClient({18 queryClient,19 persister: localStoragePersister,20});Retries
Persistence can fail, e.g. if the size exceeds the available space on the storage. Errors can be handled gracefully by providing a retry function to the persister.
The retry function receives the persistedClient it tried to save, as well as the error and the errorCount as input. It is expected to return a new PersistedClient, with which it tries to persist again. If undefined is returned, there will be no further attempt to persist.
1export type PersistRetryer = (props: {2 persistedClient: PersistedClient;3 error: Error;4 errorCount: number;5}) => PersistedClient | undefined;Predefined strategies
Per default, no retry will occur. You can use one of the predefined strategies to handle retries. They can be imported from '@tanstack/react-query-persist-client':
removeOldestQuery- will return a new
PersistedClientwith the oldest query removed.
- will return a new
1const localStoragePersister = createSyncStoragePersister({2 storage: window.localStorage,3 retry: removeOldestQuery,4});API
createSyncStoragePersister
Call this function to create a syncStoragePersister that you can use later with persistQueryClient.
1createSyncStoragePersister(options: CreateSyncStoragePersisterOptions)Options
1interface CreateSyncStoragePersisterOptions {2 /** The storage client used for setting an retrieving items from cache (window.localStorage or window.sessionStorage) */3 storage: Storage | undefined | null;4 /** The key to use when storing the cache */5 key?: string;6 /** To avoid spamming,7 * pass a time in ms to throttle saving the cache to disk */8 throttleTime?: number;9 /** How to serialize the data to storage */10 serialize?: (client: PersistedClient) => string;11 /** How to deserialize the data from storage */12 deserialize?: (cachedString: string) => PersistedClient;13 /** How to retry persistence on error **/14 retry?: PersistRetryer;15}The default options are:
1{2 key = `REACT_QUERY_OFFLINE_CACHE`,3 throttleTime = 1000,4 serialize = JSON.stringify,5 deserialize = JSON.parse,6}serialize and deserialize options
There is a limit to the amount of data which can be stored in localStorage.
If you need to store more data in localStorage, you can override the serialize and deserialize functions to compress and decrompress the data using a library like lz-string.
1import { QueryClient } from "@tanstack/react-query";2import { persistQueryClient } from "@tanstack/react-query-persist-client";3import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister";4 5import { compress, decompress } from "lz-string";6 7const queryClient = new QueryClient({8 defaultOptions: { queries: { staleTime: Infinity } },9});10 11persistQueryClient({12 queryClient: connectionsQueryClient,13 persistor: createSyncStoragePersister({14 storage: window.localStorage,15 serialize: (data) => compress(JSON.stringify(data)),16 deserialize: (data) => JSON.parse(decompress(data)),17 }),18 maxAge: Infinity,19});