Transfer prefetched queries from server-rendered markup to a browser QueryClient.
Server-side rendering
TanStack · Function
dehydrate
Converts a QueryClient cache into a serializable DehydratedState for transferring prefetched data, commonly from server to client. It includes successful queries and paused mutations by default, with options for selection and transformation.
How it works
dehydrate converts a QueryClient cache into a plain, serializable DehydratedState containing selected queries and mutations. By default, successful queries and paused mutations are included; options can change inclusion rules and transform data or errors before the result is passed to hydrate.
Syntax
function dehydrate(client: QueryClient, options?: DehydrateOptions): DehydratedState;Parameters
| Name | Type | Description |
|---|---|---|
client | QueryClient | The QueryClient whose cache is converted to dehydrated state. |
options | DehydrateOptions | Optional controls for selecting queries and mutations and transforming their data or errors; defaults to an empty options object. |
Returns
DehydratedState containing the included dehydrated queries and mutations.
Key points
- It captures both query and mutation cache entries from the supplied QueryClient.
- The result is intended to be represented as ordinary serializable state.
- A primary use is transferring prefetched server data through rendered output.
- The produced state is designed to be restored into another QueryClient.
- DehydrateOptions controls selection and transformation of cached data and errors.
Common mistakes
- Mutations are not all exported automatically; the default includes only paused mutations.
- Queries that are loading or failed are omitted unless the dehydrate configuration explicitly includes them.
- Per-call options inherit from the QueryClient's dehydrate defaults when not supplied.
Example: Dehydrate a prefetched query
import { QueryClient, dehydrate } from '@tanstack/query-core'
const queryClient = new QueryClient()
await queryClient.prefetchQuery({
queryKey: ['posts'],
queryFn: async () => fetch('/api/posts').then((r) => r.json()),
})
const dehydratedState = dehydrate(queryClient)
console.log(JSON.stringify(dehydratedState))Prefetches posts into a query client and converts its cache into a serializable state suitable for transferring to another environment.
When to use it
Serialize selected cache entries for storage in a persistent location.
State persistence
Choose which queries or mutations to include and transform their data or errors.
Custom cache export
Interview questions
QWhat does dehydrate do?
dehydrate takes a QueryClient and optional DehydrateOptions, then returns a DehydratedState. The result represents the cache in a plain serializable form for later restoration with hydrate.
Follow-up: How are inclusion and transformation policies selected? The call's options take precedence, then the client's dehydrate defaults, then the library defaults for queries and mutations.
QWhat does dehydrate include by default?
The default output contains dehydrated queries that succeeded and dehydrated mutations that are paused. Other entries require configuration through DehydrateOptions or client defaults.
Follow-up: Why might a failed query be absent from server-rendered state? Because successful queries are the default query inclusion set, so the query must be explicitly selected if failures should be transferred.
QHow is dehydrate used in server rendering?
A common flow is to prefetch data into a QueryClient, call dehydrate, serialize or embed the resulting state, and later restore it into a client QueryClient with hydrate. This supports server-rendered markup and client startup with prefetched data.
Follow-up: What does the returned state contain? It has mutations and queries collections, whose entries are represented by DehydratedMutation and DehydratedQuery types.
Related
QueryClientDehydrateOptionsDehydratedStateDehydratedQueryDehydratedMutationhydratedefaultShouldDehydrateQuerydefaultShouldDehydrateMutation