|
| 1 | +Vue Query supports two ways of prefetching data on the server and passing that to the queryClient. |
| 2 | + |
| 3 | +- Prefetch the data yourself and pass it in as `initialData` |
| 4 | + - Quick to set up for simple cases |
| 5 | + - Has some caveats |
| 6 | +- Prefetch the query on the server, dehydrate the cache and rehydrate it on the client |
| 7 | + - Requires slightly more setup up front |
| 8 | + |
| 9 | +## Using Nuxt.js |
| 10 | + |
| 11 | +### Using Hydration |
| 12 | + |
| 13 | +Vue Query supports prefetching multiple queries on the server in Nuxt.js and then _dehydrating_ those queries to the queryClient. This means the server can prerender markup that is immediately available on page load and as soon as JS is available, Vue 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. |
| 14 | + |
| 15 | +To support caching queries on the server and set up hydration: |
| 16 | + |
| 17 | +- Use `useNuxtQueryProvider` inside setup function of your layout component |
| 18 | + |
| 19 | +```js |
| 20 | +// layouts/default.vue |
| 21 | +<template> |
| 22 | + <div> |
| 23 | + <nuxt /> |
| 24 | + </div> |
| 25 | +</template> |
| 26 | + |
| 27 | +<script> |
| 28 | +import { defineComponent } from "@nuxtjs/composition-api"; |
| 29 | +import { useNuxtQueryProvider } from "vue-query/ssr"; |
| 30 | + |
| 31 | +export default defineComponent({ |
| 32 | + setup() { |
| 33 | + useNuxtQueryProvider(); |
| 34 | + }, |
| 35 | +}); |
| 36 | +</script> |
| 37 | + |
| 38 | +``` |
| 39 | + |
| 40 | +Now you are ready to prefetch some data in your pages with `onServerPrefetch`. |
| 41 | + |
| 42 | +- Use `useQueryClient` to get server-side instance of queryClient |
| 43 | +- Use `useContext` to get nuxt context |
| 44 | +- Prefetch all the queries that you need with `prefetchQuery` |
| 45 | +- Use `useNuxtDehydrate` to dehydrate the query cache and pass it to the client-side via nuxt context. |
| 46 | + |
| 47 | +```js |
| 48 | +// pages/todos.vue |
| 49 | +<template> |
| 50 | + <div> |
| 51 | + <button @click="refetch">Refetch</button> |
| 52 | + <p>{{ data }}</p> |
| 53 | + </div> |
| 54 | +</template> |
| 55 | + |
| 56 | +<script lang="ts"> |
| 57 | +import { |
| 58 | + defineComponent, |
| 59 | + onServerPrefetch, |
| 60 | + useContext, |
| 61 | +} from "@nuxtjs/composition-api"; |
| 62 | +import { useQuery, useQueryClient } from "vue-query"; |
| 63 | +import { useNuxtDehydrate } from "vue-query/ssr"; |
| 64 | + |
| 65 | +export default defineComponent({ |
| 66 | + setup() { |
| 67 | + // This will be prefetched and sent from the server |
| 68 | + const { refetch, data } = useQuery("todos", getTodos); |
| 69 | + // This won't be prefetched, it will start fetching on client side |
| 70 | + const { data2 } = useQuery("todos2", getTodos); |
| 71 | + |
| 72 | + onServerPrefetch(async () => { |
| 73 | + const { ssrContext } = useContext(); |
| 74 | + const queryClient = useQueryClient(); |
| 75 | + await queryClient.prefetchQuery("todos", getTodos); |
| 76 | + |
| 77 | + useNuxtDehydrate(ssrContext, queryClient); |
| 78 | + }); |
| 79 | + |
| 80 | + return { |
| 81 | + refetch, |
| 82 | + data, |
| 83 | + }; |
| 84 | + }, |
| 85 | +}); |
| 86 | +</script> |
| 87 | +``` |
| 88 | + |
| 89 | +As demonstrated, it's fine to prefetch some queries and let others fetch on the queryClient. This means you can control what content server renders or not by adding or removing `prefetchQuery` for a specific query. |
| 90 | + |
| 91 | +## Tips, Tricks and Caveats |
| 92 | + |
| 93 | +### Only successful queries are included in dehydration |
| 94 | + |
| 95 | +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 queryClient. This happens regardless of error. |
| 96 | + |
| 97 | +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. |
| 98 | + |
| 99 | +### Staleness is measured from when the query was fetched on the server |
| 100 | + |
| 101 | +A query is considered stale depending on when it was `dataUpdatedAt`. 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. |
| 102 | + |
| 103 | +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. |
| 104 | + |
| 105 | +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