diff --git a/docs/1.getting-started/6.data-fetching.md b/docs/1.getting-started/6.data-fetching.md index e0f4884f16..756daaa36d 100644 --- a/docs/1.getting-started/6.data-fetching.md +++ b/docs/1.getting-started/6.data-fetching.md @@ -9,20 +9,16 @@ Nuxt comes with two composables and a built-in library to perform data-fetching In a nutshell: - [`$fetch`](/docs/api/utils/dollarfetch) is the simplest way to make a network request. -- [`useFetch`](/docs/api/composables/use-fetch) is the SSR-friendly version of `$fetch` that prevent hydration mismatches. +- [`useFetch`](/docs/api/composables/use-fetch) is wrapper around `$fetch` that fetches data only once in [universal rendering](/docs/guide/concepts/rendering#universal-rendering). - [`useAsyncData`](/docs/api/composables/use-async-data) is similar to `useFetch` but offers more fine-grained control. Both `useFetch` and `useAsyncData` share a common set of options and patterns that we will detail in the last sections. -Before that, it's imperative to know why these composables exist in the first place. +## The need for `useFetch` and `useAsyncData` -## Why use specific composables for data fetching? +Nuxt is a framework which can run isomorphic (or universal) code in both server and client environments. If the [`$fetch` function](/docs/api/utils/dollarfetch) is used to perform data fetching in the setup function of a Vue component, this may cause data to be fetched twice, once on the server (to render the HTML) and once again on the client (when the HTML is hydrated). This invites the application to cause hydration issues and other unpredictable behaviours. -Nuxt is a framework which can run isomorphic (or universal) code in both server and client environments. If the [`$fetch` function](/docs/api/utils/dollarfetch) is used to perform data fetching in the setup function of a Vue component, this may cause data to be fetched twice, once on the server (to render the HTML) and once again on the client (when the HTML is hydrated). This is why Nuxt offers specific data fetching composables so data is fetched only once. - -### Network calls duplication - -The [`useFetch`](/docs/api/composables/use-fetch) and [`useAsyncData`](/docs/api/composables/use-async-data) composables ensure that once an API call is made on the server, the data is properly forwarded to the client in the payload. +The [`useFetch`](/docs/api/composables/use-fetch) and [`useAsyncData`](/docs/api/composables/use-async-data) composables solves this problem by ensuring that once an API call is made on the server, the data is properly forwarded to the client in the payload. The payload is a JavaScript object accessible through [`useNuxtApp().payload`](/docs/api/composables/use-nuxt-app#payload). It is used on the client to avoid refetching the same data when the code is executed in the browser [during hydration](/docs/guide/concepts/rendering#universal-rendering). @@ -66,9 +62,35 @@ Nuxt uses Vue’s [``](https://vuejs.org/guide/built-ins/suspense) com You can add the [``](/docs/api/components/nuxt-loading-indicator) to add a progress bar between page navigations. :: +## `$fetch` + +Nuxt includes the [ofetch](https://github.com/unjs/ofetch) library, and is auto-imported as the `$fetch` alias globally across your application. + +```vue twoslash [pages/todos.vue] + +``` + +::warning +Beware that using only `$fetch` will not provide [network calls de-duplication and navigation prevention](#the-need-for-usefetch-and-useasyncdata). :br +It is recommended to use `$fetch` for client-side interactions (event based) or combined with [`useAsyncData`](#useasyncdata) when fetching the initial component data. +:: + +::read-more{to="/docs/api/utils/dollarfetch"} +Read more about `$fetch`. +:: + ## `useFetch` -The [`useFetch`](/docs/api/composables/use-fetch) composable is the most straightforward way to perform SSR-safe data fetching. +The [`useFetch`](/docs/api/composables/use-fetch) composable uses `$fetch` under-the-hood to make SSR-safe network calls in the setup function. ```vue twoslash [app.vue] -``` - -::warning -Beware that using only `$fetch` will not provide [network calls de-duplication and navigation prevention](#why-use-specific-composables-for-data-fetching). :br -It is recommended to use `$fetch` for client-side interactions (event based) or combined with [`useAsyncData`](#useasyncdata) when fetching the initial component data. -:: - -::read-more{to="/docs/api/utils/dollarfetch"} -Read more about `$fetch`. -:: - ## `useAsyncData` The `useAsyncData` composable is responsible for wrapping async logic and returning the result once it is resolved.