Open History to see the last commit
1---
2id: persistQueryClient
3title: persistQueryClient (Experimental)
4---
5β
6> VERY IMPORTANT: This utility is currently in an experimental stage. This means that breaking changes will happen in minor AND patch releases. Use at your own risk. If you choose to rely on this in production in an experimental stage, please lock your version to a patch-level version to avoid unexpected breakages.
7β
8`persistQueryClient` is a utility for persisting the state of your queryClient and its caches for later use. Different **persistors** can be used to store your client and cache to many different storage layers.
9β
10## Officially Supported Persistors
11β
12- [createWebStoragePersistor (Experimental)](/plugins/createWebStoragePersistor)
13- [createAsyncStoragePersistor (Experimental)](/plugins/createAsyncStoragePersistor)
14β
15## Installation
16β
17This utility comes packaged with `react-query` and is available under the `react-query/persistQueryClient-experimental` import.
18β
19## Usage
20β
21Import the `persistQueryClient` function, and pass it your `QueryClient` instance (with a `cacheTime` set), and a Persistor interface (there are multiple persistor types you can use):
22β
23```ts
24import { persistQueryClient } from 'react-query/persistQueryClient-experimental'
25import { createWebStoragePersistor } from 'react-query/createWebStoragePersistor-experimental'
26β
27const queryClient = new QueryClient({
28 defaultOptions: {
29 queries: {
30 cacheTime: 1000 * 60 * 60 * 24, // 24 hours
31 },
32 },
33})
34β
35const localStoragePersistor = createWebStoragePersistor({storage: window.localStorage})
36β
37persistQueryClient({
38 queryClient,
39 persistor: localStoragePersistor,
40})
41```
42β
43**IMPORTANT** - for persist to work properly, you need to pass `QueryClient` a `cacheTime` value to override the default during hydration (as shown above).
44β
45If 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.
46β
47It 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.
48β
49You can also pass it `Infinity` to disable garbage collection behavior entirely.
50β
51## How does it work?
52β
53As you use your application:
54β
55- When your query/mutation cache is updated, it will be dehydrated and stored by the persistor you provided. **By default**, this action is throttled to happen at most every 1 second to save on potentially expensive writes to a persistor, but can be customized as you see fit.
56β
57When you reload/bootstrap your app:
58β
59- Attempts to load a previously persisted dehydrated query/mutation cache from the persistor
60- 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.
61β
62## Cache Busting
63β
64Sometimes 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.
65β
66```ts
67persistQueryClient({ queryClient, persistor, buster: buildHash })
68```
69β
70## API
71β
72### `persistQueryClient`
73β
74Pass this function a `QueryClient` instance and a persistor that will persist your cache. Both are **required**
75β
76```ts
77persistQueryClient({ queryClient, persistor })
78```
79β
80### `Options`
81β
82An object of options:
83β
84```ts
85interface PersistQueryClientOptions {
86 /** The QueryClient to persist */
87 queryClient: QueryClient
88 /** The Persistor interface for storing and restoring the cache
89 * to/from a persisted location */
90 persistor: Persistor
91 /** The max-allowed age of the cache.
92 * If a persisted cache is found that is older than this
93 * time, it will be discarded */
94 maxAge?: number
95 /** A unique string that can be used to forcefully
96 * invalidate existing caches if they do not share the same buster string */
97 buster?: string
98 /** The options passed to the hydrate function */
99 hydrateOptions?: HydrateOptions
100 /** The options passed to the dehydrate function */
101 dehydrateOptions?: DehydrateOptions
102}
103```
104β
105The default options are:
106β
107```ts
108{
109 maxAge = 1000 * 60 * 60 * 24, // 24 hours
110 buster = '',
111}
112```
113β
114## Building a Persistor
115β
116Persistors have the following interface:
117β
118```ts
119export interface Persistor {
120 persistClient(persistClient: PersistedClient): Promisable<void>
121 restoreClient(): Promisable<PersistedClient | undefined>
122 removeClient(): Promisable<void>
123}
124```
125β
126Persisted Client entries have the following interface:
127β
128```ts
129export interface PersistedClient {
130 timestamp: number
131 buster: string
132 cacheState: any
133}
134```
135β
136Satisfy all of these interfaces and you've got yourself a persistor!