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

hydration.md

128 lines5.1 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 `HydrationBoundary` 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```tsx
11import { dehydrate } from '@tanstack/react-query'
12​
13const dehydratedState = dehydrate(queryClient, {
14 shouldDehydrateQuery,
15 shouldDehydrateMutation,
16})
17```
18​
19**Options**
20​
21- `client: QueryClient`
22 - **Required**
23 - The `queryClient` that should be dehydrated
24- `options: DehydrateOptions`
25 - Optional
26 - `shouldDehydrateMutation: (mutation: Mutation) => boolean`
27 - Optional
28 - Whether to dehydrate mutations.
29 - The function is called for each mutation in the cache
30 - Return `true` to include this mutation in dehydration, or `false` otherwise
31 - Defaults to only including paused mutations
32 - If you would like to extend the function while retaining the default behavior, import and execute `defaultShouldDehydrateMutation` as part of the return statement
33 - `shouldDehydrateQuery: (query: Query) => boolean`
34 - Optional
35 - Whether to dehydrate queries.
36 - The function is called for each query in the cache
37 - Return `true` to include this query in dehydration, or `false` otherwise
38 - Defaults to only including successful queries
39 - If you would like to extend the function while retaining the default behavior, import and execute `defaultShouldDehydrateQuery` as part of the return statement
40 - `serializeData?: (data: any) => any` A function to transform (serialize) data during dehydration.
41 - `shouldRedactErrors?: (error: unknown) => boolean`
42 - Optional
43 - Whether to redact errors from the server during dehydration.
44 - The function is called for each error in the cache
45 - Return `true` to redact this error, or `false` otherwise
46 - Defaults to redacting all errors
47​
48**Returns**
49​
50- `dehydratedState: DehydratedState`
51 - This includes everything that is needed to hydrate the `queryClient` at a later point
52 - 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
53 - This result is not in serialized form, you need to do that yourself if desired
54​
55### Limitations
56​
57Some storage systems (such as browser [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API)) require 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.:
58​
59```tsx
60// server
61const state = dehydrate(client, { shouldDehydrateQuery: () => true }) // to also include Errors
62const serializedState = mySerialize(state) // transform Error instances to objects
63​
64// client
65const state = myDeserialize(serializedState) // transform objects back to Error instances
66hydrate(client, state)
67```
68​
69## `hydrate`
70​
71`hydrate` adds a previously dehydrated state into a `cache`.
72​
73```tsx
74import { hydrate } from '@tanstack/react-query'
75​
76hydrate(queryClient, dehydratedState, options)
77```
78​
79**Options**
80​
81- `client: QueryClient`
82 - **Required**
83 - The `queryClient` to hydrate the state into
84- `dehydratedState: DehydratedState`
85 - **Required**
86 - The state to hydrate into the client
87- `options: HydrateOptions`
88 - Optional
89 - `defaultOptions: DefaultOptions`
90 - Optional
91 - `mutations: MutationOptions` The default mutation options to use for the hydrated mutations.
92 - `queries: QueryOptions` The default query options to use for the hydrated queries.
93 - `deserializeData?: (data: any) => any` A function to transform (deserialize) data before it is put into the cache.
94 - `queryClient?: QueryClient`
95 - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
96​
97### Limitations
98​
99If the queries you're trying to hydrate already exist in the queryCache, `hydrate` will only overwrite them if the data is newer than the data present in the cache. Otherwise, it will **not** get applied.
100​
101[//]: # 'HydrationBoundary'
102​
103## `HydrationBoundary`
104​
105`HydrationBoundary` 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.
106​
107```tsx
108import { HydrationBoundary } from '@tanstack/react-query'
109​
110function App() {
111 return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>
113```
114​
115> Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
116​
117**Options**
118​
119- `state: DehydratedState`
120 - The state to hydrate
121- `options: HydrateOptions`
122 - Optional
123 - `defaultOptions: QueryOptions`
124 - The default query options to use for the hydrated queries.
125 - `queryClient?: QueryClient`
126 - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.
127​
128[//]: # 'HydrationBoundary'