persistQueryClient

persistQueryClient is a utility for persisting the state of your queryClient and its caches for later use. Different persisters can be used to store your client and cache to many different storage layers.

Officially Supported Persisters

• createWebStoragePersister
• createAsyncStoragePersister

Installation

This utility comes packaged with react-query and is available under the react-query/persistQueryClient import.

Usage

Import the persistQueryClient function, and pass it your QueryClient instance (with a cacheTime set), and a Persister interface (there are multiple persister types you can use):

1 import { persistQueryClient } from 'react-query/persistQueryClient'
2 import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
3 
4 const queryClient = new QueryClient({
5   defaultOptions: {
6     queries: {
7       cacheTime: 1000 * 60 * 60 * 24, // 24 hours
8     },
9   },
10 })
11 
12 const localStoragePersister = createWebStoragePersister({
13   storage: window.localStorage,
14 })
15 
16 persistQueryClient({
17   queryClient,
18   persister: localStoragePersister,
19 })

IMPORTANT - for persist to work properly, you need to pass QueryClient a cacheTime value to override the default during hydration (as shown above).

If it is not set when creating the QueryClient instance, it will default to 300000 (5 minutes) for hydration, and the stored cache will be discarded after 5 minutes of inactivity. This is the default garbage collection behavior.

It should be set as the same value or higher than persistQueryClient's maxAge option. E.g. if maxAge is 24 hours (the default) then cacheTime should be 24 hours or higher. If lower than maxAge, garbage collection will kick in and discard the stored cache earlier than expected.

You can also pass it Infinity to disable garbage collection behavior entirely.

How does it work?

• A check for window undefined is performed prior to saving/restoring/removing your data (avoids build errors).

Storing

As you use your application:

• When your query/mutation cache is updated, it will be dehydrated and stored by the persister you provided. The officially supported persisters throttle this action to happen at most every 1 second to save on potentially expensive writes, but can be customized as you see fit.

Cache Busting

Sometimes you may make changes to your application or data that immediately invalidate any and all cached data. If and when this happens, you can pass a buster string option to persistQueryClient, and if the cache that is found does not also have that buster string, it will be discarded.

 persistQueryClient({ queryClient, persister, buster: buildHash })

Restoring

When you reload/bootstrap your app:

• Attempts to hydrate a previously persisted dehydrated query/mutation cache from the persister back into the query cache of the passed query client.
• If a cache is found that is older than the maxAge (which by default is 24 hours), it will be discarded. This can be customized as you see fit.

Removal

• If data is found to be expired (see maxAge), busted (see buster), error (ex: throws ...), or empty (ex: undefined), the persister removeClient() is called and the cache is immediately discarded.

API

persistQueryClientRestore

This will attempt to restore a persister's stored cached to the query cache of the passed queryClient.

1 persistQueryClientRestore({
2   queryClient,
3   persister,
4   maxAge = 1000 * 60 * 60 * 24, // 24 hours
5   buster = '',
6   hydrateOptions = undefined,
7 })

persistQueryClientSave

This will attempt to save the current query cache with the persister. You can use this to explicitly persist the cache at the moments you choose.

1 persistQueryClientSave({
2   queryClient,
3   persister,
4   buster = '',
5   dehydrateOptions = undefined,
6 })

persistQueryClientSubscribe

This will subscribe to query cache updates which will run persistQueryClientSave. For example: you might initiate the subscribe when a user logs-in and checks "Remember me".

• It returns an unsubscribe function which you can use to discontinue the monitor; ending the updates to the persisted cache.
• If you want to erase the persisted cache after the unsubscribe, you can send a new buster to persistQueryClientRestore which will trigger the persister's removeClient function and discard the persisted cache.

1 persistQueryClientSubscribe({
2   queryClient,
3   persister,
4   buster = '',
5   dehydrateOptions = undefined,
6 })

persistQueryClient

This will automatically restore any persisted cache and subscribes to the query cache to persist any changes from the query cache to the persister. It returns an unsubscribe function which you can use to discontinue the monitor; ending the updates to the persisted cache.

1 persistQueryClient({
2   queryClient,
3   persister,
4   maxAge = 1000 * 60 * 60 * 24, // 24 hours
5   buster = '',
6   hydrateOptions = undefined,
7   dehydrateOptions = undefined,
8 })

Options

An object of options:

1 interface PersistQueryClientOptions {
2   /** The QueryClient to persist */
3   queryClient: QueryClient
4   /** The Persister interface for storing and restoring the cache
5    * to/from a persisted location */
6   persister: Persister
7   /** The max-allowed age of the cache in milliseconds.
8    * If a persisted cache is found that is older than this
9    * time, it will be **silently** discarded
10    * (defaults to 24 hours) */
11   maxAge?: number
12   /** A unique string that can be used to forcefully
13    * invalidate existing caches if they do not share the same buster string */
14   buster?: string
15   /** The options passed to the hydrate function */
16   hydrateOptions?: HydrateOptions
17   /** The options passed to the dehydrate function */
18   dehydrateOptions?: DehydrateOptions
19 }

Building a Persister

Persisters have the following interface:

1 export interface Persister {
2   persistClient(persistClient: PersistedClient): Promisable<void>
3   restoreClient(): Promisable<PersistedClient | undefined>
4   removeClient(): Promisable<void>
5 }

Persisted Client entries have the following interface:

1 export interface PersistedClient {
2   timestamp: number
3   buster: string
4   cacheState: any
5 }

Satisfy all of these interfaces and you've got yourself a persister!