diff --git a/docs/1.getting-started/6.data-fetching.md b/docs/1.getting-started/6.data-fetching.md index 9e4e0a47ae..7dff19f2c8 100644 --- a/docs/1.getting-started/6.data-fetching.md +++ b/docs/1.getting-started/6.data-fetching.md @@ -88,6 +88,37 @@ It is recommended to use `$fetch` for client-side interactions (event based) or Read more about `$fetch`. :: +### Pass Client Headers to the API + +During server-side-rendering, since the `$fetch` request takes place 'internally' within the server, it won't include the user's browser cookies. + +We can use [`useRequestHeaders`](/docs/api/composables/use-request-headers) to access and proxy cookies to the API from server-side. + +The example below adds the request headers to an isomorphic `$fetch` call to ensure that the API endpoint has access to the same `cookie` header originally sent by the user. + +```vue + +``` + +::caution +Be very careful before proxying headers to an external API and just include headers that you need. Not all headers are safe to be bypassed and might introduce unwanted behavior. Here is a list of common headers that are NOT to be proxied: + +- `host`, `accept` +- `content-length`, `content-md5`, `content-type` +- `x-forwarded-host`, `x-forwarded-port`, `x-forwarded-proto` +- `cf-connecting-ip`, `cf-ray` +:: + +::tip +You can also use [`useRequestFetch`](/docs/api/composables/use-request-fetch) to proxy headers to the call automatically. +::: + ## `useFetch` The [`useFetch`](/docs/api/composables/use-fetch) composable uses `$fetch` under-the-hood to make SSR-safe network calls in the setup function. @@ -117,8 +148,8 @@ Watch the video from Alexander Lichter to avoid using `useFetch` the wrong way! The `useAsyncData` composable is responsible for wrapping async logic and returning the result once it is resolved. ::tip -`useFetch(url)` is nearly equivalent to `useAsyncData(url, () => $fetch(url))`. :br -It's developer experience sugar for the most common use case. +`useFetch(url)` is nearly equivalent to `useAsyncData(url, () => event.$fetch(url))`. :br +It's developer experience sugar for the most common use case. (You can find out more about `event.fetch` at [`useRequestFetch`](/docs/api/composables/use-request-fetch).) :: ::tip{icon="i-ph-video" to="https://www.youtube.com/watch?v=0X-aOpSGabA" target="_blank"} @@ -458,32 +489,13 @@ For finer control, the `status` variable can be: - `error` when the fetch fails - `success` when the fetch is completed successfully -## Passing Headers and cookies +## Passing Headers and Cookies -When we call `$fetch` in the browser, user headers like `cookie` will be directly sent to the API. But during server-side-rendering, since the `$fetch` request takes place 'internally' within the server, it doesn't include the user's browser cookies, nor does it pass on cookies from the fetch response. +When we call `$fetch` in the browser, user headers like `cookie` will be directly sent to the API. -### Pass Client Headers to the API +Normally, during server-side-rendering, since the `$fetch` request takes place 'internally' within the server, it wouldn't include the user's browser cookies, nor pass on cookies from the fetch response. -We can use [`useRequestHeaders`](/docs/api/composables/use-request-headers) to access and proxy cookies to the API from server-side. - -The example below adds the request headers to an isomorphic `$fetch` call to ensure that the API endpoint has access to the same `cookie` header originally sent by the user. - -```vue - -``` - -::caution -Be very careful before proxying headers to an external API and just include headers that you need. Not all headers are safe to be bypassed and might introduce unwanted behavior. Here is a list of common headers that are NOT to be proxied: - -- `host`, `accept` -- `content-length`, `content-md5`, `content-type` -- `x-forwarded-host`, `x-forwarded-port`, `x-forwarded-proto` -- `cf-connecting-ip`, `cf-ray` -:: +However, when calling `useFetch` on the server, Nuxt will use [`useRequestFetch`](/docs/api/composables/use-request-fetch) to proxy headers and cookies (with the exception of headers not meant to be forwarded, like `host`). ### Pass Cookies From Server-side API Calls on SSR Response