You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* chore(hydration): set up separate hydration entry point
* feat(hydration): add support for de/rehydrating queryCaches
- Add dehydrate(queryCache, config)
- Add hydrate(queryCache, dehydratedQueries, config)
- Add useHydrate(dehydratedQueries, config)
* test(hydration): fix broken type in test
* rename scheduleTimeoutsManually to activateTimeoutsManually
* docs(hydration): add API-docs for hydration and update comparison
* docs(ssr): update ssr-docs with new approach based on de/rehydration
* remove activateTimeoutsManually
* add default shouldDehydrate
* add hydration/ReactQueryCacheProvider
* use unknown for initialData in dehydration
* rename initialQueries and dehydratedQueries to dehydratedState
* include queryKey instead of queryHash in dehydration
* update initialQueries to dehydratedState in ssr guide docs
* remove shouldHydrate-option
The `queryCache` instance is the backbone of React Query that manages all of the state, caching, lifecycle and magic of every query. It supports relatively unrestricted, but safe, access to manipulate query's as you need. Its available properties and methods are:
- This will be an array containing the queries that were found.
633
648
649
+
## `makeQueryCache`
650
+
651
+
`makeQueryCache` creates an empty `queryCache` manually. This is useful together with `ReactQueryCacheProvider` to have multiple caches in your application.
652
+
653
+
As opposed to the global cache, caches created by `makeQueryCache` caches data even on the server.
654
+
655
+
```js
656
+
import { makeQueryCache } from'react-query'
657
+
658
+
constqueryCache=makeQueryCache()
659
+
```
660
+
661
+
**Returns**
662
+
663
+
- `queryCache: QueryCache`
664
+
- An empty `queryCache`
665
+
634
666
## `useQueryCache`
635
667
636
668
The `useQueryCache` hook returns the current queryCache instance.
@@ -734,7 +766,7 @@ function App() {
734
766
735
767
**Options**
736
768
737
-
- `queryCache:Object`
769
+
- `queryCache:QueryCache`
738
770
- In instance of queryCache, you can use the `makeQueryCache` factory to create this.
739
771
- If not provided, a new cache will be generated.
740
772
@@ -757,3 +789,96 @@ setConsole({
757
789
758
790
- `console:Object`
759
791
- Must implement the `log`, `warn`, and `error` methods.
792
+
793
+
## `hydration/dehydrate`
794
+
795
+
`dehydrate` creates a frozen representation of a `queryCache` that can later be hydrated with `useHydrate`, `hydrate` or by passing it into `hydration/ReactQueryCacheProvider`. This is useful for passing prefetched queries from server to client or persisting queries to localstorage. It only includes currently successful queries by default.
- This function is called for each query in the cache
812
+
- Return `true` to include this query in dehydration, or `false` otherwise
813
+
- Default version only includes successful queries, do `shouldDehydrate: () =>true` to include all queries
814
+
815
+
**Returns**
816
+
817
+
- `dehydratedState: DehydratedState`
818
+
- This includes everything that is needed to hydrate the `queryCache` at a later point
819
+
- 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
820
+
- This result is not in serialized form, you need to do that yourself if desired
821
+
822
+
## `hydration/hydrate`
823
+
824
+
`hydrate` adds a previously dehydrated state into a `queryCache`. If the queries included in dehydration already exist in the cache, `hydrate` does not overwrite them.
825
+
826
+
```js
827
+
import { hydrate } from'react-query/hydration'
828
+
829
+
hydrate(queryCache, dehydratedState)
830
+
```
831
+
832
+
**Options**
833
+
834
+
- `queryCache: QueryCache`
835
+
- **Required**
836
+
- The `queryCache` to hydrate the state into
837
+
- `dehydratedState: DehydratedState`
838
+
- **Required**
839
+
- The state to hydrate into the cache
840
+
841
+
## `hydration/useHydrate`
842
+
843
+
`useHydrate` adds a previously dehydrated state into the `queryCache` returned by `useQueryCache`.
844
+
845
+
```jsx
846
+
import { useHydrate } from'react-query/hydration'
847
+
848
+
useHydrate(dehydratedState)
849
+
```
850
+
851
+
**Options**
852
+
853
+
- `dehydratedState: DehydratedState`
854
+
- **Required**
855
+
- The state to hydrate
856
+
857
+
## `hydration/ReactQueryCacheProvider`
858
+
859
+
`hydration/ReactQueryCacheProvider` does the same thing as `ReactQueryCacheProvider` but also supports hydrating an initial state into the cache.
If your queries are for data that is frequently updating and you don't necessarily need the data to be preset at render time (for SEO or performance purposes), then you don't need any extra configuration for React Query! Just import `useQuery` and fetch data right from within your components.
8
+
If your queries are for data that is frequently updating and you don't necessarily need the data to be present at page load time (for SEO or performance purposes), then you don't need any extra configuration for React Query! Just import `useQuery` and fetch data right from within your components.
9
9
10
-
This approach works well for applications or user-specific pages that might contain private or non-public/non-generic information. SEO is usually not relevant to these types of pages and full SSR of data is rarely needed in said situations.
10
+
This approach works well for applications or user-specific pages that might contain private or non-public/non-generic information. SEO is usually not as relevant to these types of pages and full SSR of data is rarely needed in said situations.
11
11
12
-
## Pre-rendering
12
+
## Server Side Rendering Overview
13
13
14
-
If the page and its data needs to be rendered on the server, React Query comes built in with mechanisms to support this use case. The exact implementation of these mechanisms may vary from platform to platform, but we recommend starting with Next.js which supports [2 forms of pre-rendering](https://nextjs.org/docs/basic-features/data-fetching):
14
+
React Query supports two ways of prefetching data on the server and passing that to the client.
15
+
16
+
* Prefetch the data yourself and pass it in as `initialData`
17
+
* Quick to set up for simple cases
18
+
* Has some caveats
19
+
* Prefetch the query via React Query and use de/rehydration
20
+
* Requires slightly more setup up front
21
+
22
+
The exact implementation of these mechanisms may vary from platform to platform, but we recommend starting with Next.js which supports [2 forms of pre-rendering](https://nextjs.org/docs/basic-features/data-fetching):
15
23
16
24
- Static Generation (SSG)
17
25
- Server-side Rendering (SSR)
18
26
19
-
With React Query and Next.js, you can pre-render a page for SEO and gracefully upgrade that page's queries during hydration to support caching, invalidation and background refetching on the client side.
27
+
React Query supports both of these forms of pre-rendering.
28
+
29
+
## Prefetch the data yourself and pass it in as `initialData`
20
30
21
-
For example, together with Next.js's [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation), you can pass the pre-fetched data for the page to `useQuery`'s' `initialData` option:
31
+
Together with Next.js's [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation), you can pass the pre-fetched data for the page to `useQuery`'s' `initialData` option:
22
32
23
33
```jsx
24
34
exportasyncfunctiongetStaticProps() {
25
35
constposts=awaitgetPosts()
26
36
return { props: { posts } }
27
37
}
28
38
29
-
functionProps(props) {
39
+
functionPosts(props) {
30
40
const { data } =useQuery('posts', getPosts, { initialData:props.posts })
31
41
32
42
// ...
33
43
}
34
44
```
35
45
36
-
This page would be prerendered using the data fetched in `getStaticProps` and be ready for SEO, then, as soon it mounts on the client, will also be cached and refetched/updated in the background as needed.
46
+
The setup is minimal and this can be a perfect solution for some cases, but there are a few tradeoffs compared to the full approach:
47
+
48
+
* If you are calling `useQuery` in a component deeper down in the tree you need to pass the `initialData` down to that point
49
+
* If you are calling `useQuery` with the same query in multiple locations, you need to pass `initialData` to all of them
50
+
* There is no way to know at what time the query was fetched on the server, so `updatedAt` and determining if the query needs refetching is based on when the page loaded instead
51
+
52
+
## Prefetch the query via React Query and use de/rehydration
37
53
38
-
## Advanced SSR Concepts
54
+
React Query supports prefetching a query on the server and handing off or _dehydrating_ that query to the client. This means the server can prerender markup that is immediately available on page load and as soon as JS is available, React Query can upgrade or _hydrate_ those queries with the full functionality of the library. This includes refetching those queries on the client if they have become stale since the time they were rendered on the server.
39
55
40
-
When using SSR (server-side-rendering) with React Query there are a few things to note:
56
+
### Integrating with Next.js
57
+
58
+
To support caching queries on the server and set up hydration, you start with wrapping your application with `<ReactQueryCacheProvider>` in `_app.js`.
59
+
60
+
> Note: You need to import `ReactQueryCacheProvider` from `'react-query/hydration'` for it to support hydration!
Now you are ready to prefetch some data in your pages with either [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) (for SSG) or [`getServerSideProps`](https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering) (for SSR). From React Query's perspective, these integrate in the same way, `getStaticProps` is shown below:
76
+
77
+
```jsx
78
+
// pages/posts.jsx
79
+
import { makeQueryCache } from'react-query'
80
+
import { dehydrate } from'react-query/hydration'
81
+
82
+
exportasyncfunctiongetStaticProps() {
83
+
constqueryCache=makeQueryCache()
84
+
85
+
awaitqueryCache.prefetchQuery('posts', getPosts)
86
+
87
+
return {
88
+
props: {
89
+
dehydratedState:dehydrate(queryCache)
90
+
}
91
+
}
92
+
}
41
93
42
-
- If you import and use the global `queryCache` directly, queries are not cached during SSR to avoid leaking sensitive information between requests.
43
-
- If you create a `queryCache` manually with `makeQueryCache`, queries will be cached during SSR. Make sure you create a separate cache per request to avoid leaking data.
44
-
- Queries rendered on the server will by default use the `initialData` of an unfetched query. This means that by default, `data` will be set to `undefined`. To get around this in SSR, you can either pre-seed a query's cache data using the `config.initialData` option:
94
+
functionPosts() {
95
+
// This useQuery could just as well happen in some deeper child to
96
+
// the "Posts"-page, data will be available immediately either way
97
+
const { data } =useQuery('posts', getPosts)
45
98
46
-
```js
47
-
constqueryInfo=useQuery('todos', fetchTodoList, {
48
-
initialData: [{ id:0, name:'Implement SSR!' }],
49
-
})
99
+
// This query was not prefetched on the server and will not start
100
+
// fetching until on the client, both patterns are fine to mix
Or, alternatively you can just destructure from `undefined` in your query results:
107
+
As demonstrated, it's fine to prefetch some queries and let some fetch on the client. This means you can control what content server renders or not by adding or removing `prefetchQuery` for a specific query.
108
+
109
+
### Integrating with custom SSR solutions or other frameworks
110
+
111
+
Since there are many different possible setups for SSR, it's hard to give a detailed guide for each (contributions are welcome!). Here is a thorough high level overview:
112
+
113
+
**Server side**
114
+
115
+
> Note: The global `queryCache` you can import directly from 'react-query' does not cache queries on the server to avoid leaking sensitive information between requests.
116
+
117
+
- Prefetch data
118
+
- Create a `prefetchQueryCache` specifically for prefetching by calling `const prefetchQueryCache = makeQueryCache()`
119
+
- Call `prefetchQueryCache.prefetchQuery(...)` to prefetch queries
120
+
- Dehydrate by using `const dehydratedState = dehydrate(prefetchQueryCache)`
121
+
- Render
122
+
- Wrap the app in `<ReactQueryCacheProvider>` from `'react-query/hydration'` and pass in `dehydratedState`
123
+
- This makes sure a separate `queryCache` is created specifically for rendering
124
+
-**Do not** pass in the `prefetchQueryCache` from the last step, the server and client both needs to render from the dehydrated data to avoid React hydration mismatches. This is because queries with errors are excluded from dehydration by default.
125
+
- Serialize and embed `dehydratedState` in the markup
126
+
- Security note: Serializing data with `JSON.stringify` can put you at risk for XSS-vulnerabilities, [this blog post explains why and how to solve it](https://medium.com/node-security/the-most-common-xss-vulnerability-in-react-js-applications-2bdffbcc1fa0)
127
+
128
+
**Client side**
129
+
130
+
- Parse `dehydratedState` from where you put it in the markup
131
+
- Render
132
+
- Wrap the app in `<ReactQueryCacheProvider>` from `'react-query/hydration'` and pass in `dehydratedState`
133
+
134
+
This list aims to be exhaustive, but depending on your current setup, the above steps can take more or less work. Here is a barebones example:
The query's state will still reflect that it is stale and has not been fetched yet, and once mounted, it will continue as normal and request a fresh copy of the query result.
165
+
### Tips, Tricks and Caveats
166
+
167
+
**Only successful queries are included in dehydration**
168
+
169
+
Any query with an error is automatically excluded from dehydration. This means that the default behaviour is to pretend these queries were never loaded on the server, usually showing a loading state instead, and retrying the queries on the client. This happens regardless of error.
170
+
171
+
Sometimes this behavior is not desirable, maybe you want to render an error page with a correct status code instead on certain errors or queries. In those cases, pass `throwOnError: true` to the specific `prefetchQuery` to be able to catch and handle those errors manually.
172
+
173
+
**Staleness is measured from when the query was fetched on the server**
174
+
175
+
A query is considered stale depending on when it was `updatedAt`. A caveat here is that the server needs to have the correct time for this to work properly, but UTC time is used, so timezones do not factor into this.
176
+
177
+
Because `staleTime` defaults to `0`, queries will be refetched in the background on page load by default. You might want to use a higher `staleTime` to avoid this double fetching, especially if you don't cache your markup.
178
+
179
+
This refetching of stale queries is a perfect match when caching markup in a CDN! You can set the cache time of the page itself decently high to avoid having to re-render pages on the server, but configure the `staleTime` of the queries lower to make sure data is refetched in the background as soon as a user visits the page. Maybe you want to cache the pages for a week, but refetch the data automatically on page load if it's older than a day?
0 commit comments