Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

persistQueryClient.md

136 lines4.8 KB

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
103```
104​
105The default options are:
106​
107```ts
109 maxAge = 1000 * 60 * 60 * 24, // 24 hours
110 buster = '',
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>
124```
125​
126Persisted Client entries have the following interface:
127​
128```ts
129export interface PersistedClient {
130 timestamp: number
131 buster: string
132 cacheState: any
134```
135​
136Satisfy all of these interfaces and you've got yourself a persistor!