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

hydration.md

135 lines4.8 KB

1---
2id: hydration
3title: hydration
4---
5​
6## `dehydrate`
7​
8`dehydrate` creates a frozen representation of a `cache` that can later be hydrated with `Hydrate`, `useHydrate`, or `hydrate`. This is useful for passing prefetched queries from server to client or persisting queries to localStorage or other persistent locations. It only includes currently successful queries by default.
9​
10```js
11import { dehydrate } from 'react-query'
12​
13const dehydratedState = dehydrate(queryClient, {
14 shouldDehydrateQuery,
15})
16```
17​
18> Note: Since version `3.22.0` hydration utilities moved into to core. If you using lower version your should import `dehydrate` from `react-query/hydration`
19​
20**Options**
21​
22- `client: QueryClient`
23 - **Required**
24 - The `queryClient` that should be dehydrated
25- `options: DehydrateOptions`
26 - Optional
27 - `dehydrateMutations: boolean`
28 - Optional
29 - Whether or not to dehydrate mutations.
30 - `dehydrateQueries: boolean`
31 - Optional
32 - Whether or not to dehydrate queries.
33 - `shouldDehydrateMutation: (mutation: Mutation) => boolean`
34 - Optional
35 - This function is called for each mutation in the cache
36 - Return `true` to include this mutation in dehydration, or `false` otherwise
37 - The default version only includes paused mutations
38 - `shouldDehydrateQuery: (query: Query) => boolean`
39 - Optional
40 - This function is called for each query in the cache
41 - Return `true` to include this query in dehydration, or `false` otherwise
42 - The default version only includes successful queries, do `shouldDehydrateQuery: () => true` to include all queries
43​
44**Returns**
45​
46- `dehydratedState: DehydratedState`
47 - This includes everything that is needed to hydrate the `queryClient` at a later point
48 - You **should not** rely on the exact format of this response, it is not part of the public API and can change at any time
49 - This result is not in serialized form, you need to do that yourself if desired
50​
51### limitations
52​
53The hydration API requires values to be JSON serializable. If you need to dehydrate values that are not automatically serializable to JSON (like `Error` or `undefined`), you have to serialize them for yourself. Since only successful queries are included per default, to also include `Errors`, you have to provide `shouldDehydrateQuery`, e.g.:
54​
55```js
56// server
57const state = dehydrate(client, { shouldDehydrateQuery: () => true }) // to also include Errors
58const serializedState = mySerialize(state) // transform Error instances to objects
59​
60// client
61const state = myDeserialize(serializedState) // transform objects back to Error instances
62hydrate(client, state)
63```
64​
65## `hydrate`
66​
67`hydrate` adds a previously dehydrated state into a `cache`. If the queries included in dehydration already exist in the queryCache, `hydrate` does not overwrite them.
68​
69```js
70import { hydrate } from 'react-query'
71​
72hydrate(queryClient, dehydratedState, options)
73```
74​
75> Note: Since version `3.22.0` hydration utilities moved into to core. If you using lower version your should import `hydrate` from `react-query/hydration`
76​
77**Options**
78​
79- `client: QueryClient`
80 - **Required**
81 - The `queryClient` to hydrate the state into
82- `dehydratedState: DehydratedState`
83 - **Required**
84 - The state to hydrate into the client
85- `options: HydrateOptions`
86 - Optional
87 - `defaultOptions: DefaultOptions`
88 - Optional
89 - `mutations: MutationOptions` The default mutation options to use for the hydrated mutations.
90 - `queries: QueryOptions` The default query options to use for the hydrated queries.
91​
92## `useHydrate`
93​
94`useHydrate` adds a previously dehydrated state into the `queryClient` that would be returned by `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on update timestamp.
95​
96```jsx
97import { useHydrate } from 'react-query'
98​
99useHydrate(dehydratedState, options)
100```
101​
102> Note: Since version `3.22.0` hydration utilities moved into to core. If you using lower version your should import `useHydrate` from `react-query/hydration`
103​
104**Options**
105​
106- `dehydratedState: DehydratedState`
107 - **Required**
108 - The state to hydrate
109- `options: HydrateOptions`
110 - Optional
111 - `defaultOptions: QueryOptions`
112 - The default query options to use for the hydrated queries.
113​
114## `Hydrate`
115​
116`Hydrate` wraps `useHydrate` into component. Can be useful when you need hydrate in class component or need hydrate on same level where `QueryClientProvider` rendered.
117​
118```js
119import { Hydrate } from 'react-query'
120​
121function App() {
122 return <Hydrate state={dehydratedState}>...</Hydrate>
124```
125​
126> Note: Since version `3.22.0` hydration utilities moved into to core. If you using lower version your should import `Hydrate` from `react-query/hydration`
127​
128**Options**
129​
130- `state: DehydratedState`
131 - The state to hydrate
132- `options: HydrateOptions`
133 - Optional
134 - `defaultOptions: QueryOptions`
135 - The default query options to use for the hydrated queries.