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.
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.
React Query supports two ways of prefetching data on the server and passing that to the client.
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:
React Query supports both of these forms of pre-rendering.
Together with Next.js's
getStaticProps, you can pass the pre-fetched data for the page to
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:
useQueryin a component deeper down in the tree you need to pass the
initialDatadown to that point
useQuerywith the same query in multiple locations, you need to pass
initialDatato all of them
updatedAtand determining if the query needs refetching is based on when the page loaded instead
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.
To support caching queries on the server and set up hydration, you start with wrapping your application with
Now you are ready to prefetch some data in your pages with either
getStaticProps (for SSG) or
getServerSideProps (for SSR). From React Query's perspective, these integrate in the same way,
getStaticProps is shown below:
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.
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:
Note: The global
queryCacheyou can import directly from 'react-query' does not cache queries on the server to avoid leaking sensitive information between requests.
prefetchCachespecifically for prefetching by calling
const prefetchCache = new QueryCache()
prefetchCache.prefetchQuery(...)to prefetch queries
const dehydratedState = dehydrate(prefetchCache)
prefetchCacheto render your app, 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.
dehydratedStatein the markup
JSON.stringifycan put you at risk for XSS-vulnerabilities, this blog post explains why and how to solve it
dehydratedStatefrom where you put it in the markup
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:
Only successful queries are included in dehydration
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.
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, use
fetchQuery and catch any errors to handle those manually.
Staleness is measured from when the query was fetched on the server
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.
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.
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?