From ed5fda4e7c77f5f85660e43519b85debcc6c7669 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20=C4=8Cern=C3=BD?=
 <112722215+CernyMatej@users.noreply.github.com>
Date: Sat, 21 Sep 2024 12:39:54 +0200
Subject: [PATCH] docs: add a section about `useRequestFetch` and
 `event.$fetch` (#29099)

---
 .../2.guide/2.directory-structure/1.server.md | 16 ++++++
 docs/3.api/2.composables/use-request-fetch.md | 52 +++++++++++++++++++
 2 files changed, 68 insertions(+)
 create mode 100644 docs/3.api/2.composables/use-request-fetch.md

diff --git a/docs/2.guide/2.directory-structure/1.server.md b/docs/2.guide/2.directory-structure/1.server.md
index 0f5111e3ca..cbf68709d9 100644
--- a/docs/2.guide/2.directory-structure/1.server.md
+++ b/docs/2.guide/2.directory-structure/1.server.md
@@ -347,6 +347,22 @@ export default defineEventHandler((event) => {
 })
 ```
 
+### Forwarding Context & Headers
+
+By default, neither the headers from the incoming request nor the request context are forwarded when
+making fetch requests in server routes. You can use `event.$fetch` to forward the request context and headers when making fetch requests in server routes.
+
+```ts [server/api/forward.ts]
+export default defineEventHandler((event) => {
+  return event.$fetch('/api/forwarded')
+})
+```
+
+::note
+Headers that are **not meant to be forwarded** will **not be included** in the request. These headers include, for example:
+`transfer-encoding`, `connection`, `keep-alive`, `upgrade`, `expect`, `host`, `accept`
+::
+
 ## Advanced Usage
 
 ### Nitro Config
diff --git a/docs/3.api/2.composables/use-request-fetch.md b/docs/3.api/2.composables/use-request-fetch.md
new file mode 100644
index 0000000000..dac922e393
--- /dev/null
+++ b/docs/3.api/2.composables/use-request-fetch.md
@@ -0,0 +1,52 @@
+---
+title: 'useRequestFetch'
+description: 'Forward the request context and headers for server-side fetch requests with the useRequestFetch composable.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/ssr.ts
+    size: xs
+---
+
+You can use `useRequestFetch` to forward the request context and headers when making server-side fetch requests.
+
+When making a client-side fetch request, the browser automatically sends the necessary headers.
+However, when making a request during server-side rendering, because the request is made on the server, we need to forward the headers manually.
+
+::note
+Headers that are **not meant to be forwarded** will **not be included** in the request. These headers include, for example:
+`transfer-encoding`, `connection`, `keep-alive`, `upgrade`, `expect`, `host`, `accept`
+::
+
+::tip
+The [`useFetch`](/docs/api/composables/use-fetch) composable uses `useRequestFetch` under the hood to automatically forward the request context and headers.
+::
+
+::code-group
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+  // This will forward the user's headers to the `/api/foo` event handler
+  // Result: { cookies: { foo: 'bar' } }
+  const requestFetch = useRequestFetch()
+  const { data: forwarded } = await useAsyncData(() => requestFetch('/api/cookies'))
+  
+  // This will NOT forward anything
+  // Result: { cookies: {} }
+  const { data: notForwarded } = await useAsyncData(() => $fetch('/api/cookies')) 
+</script>
+```
+
+```ts [server/api/cookies.ts]
+export default defineEventHandler((event) => {
+  const cookies = parseCookies(event)
+
+  return { cookies }
+})
+```
+
+::
+
+::tip
+In the browser during client-side navigation, `useRequestFetch` will behave just like regular [`$fetch`](/docs/api/utils/dollarfetch).
+::