docs: add custom fetch composable example (#20115)

docs/3.api/1.composables/use-fetch.md

@@ -126,6 +126,9 @@ const { data, pending, error, refresh } = await useFetch('/api/auth/login', {
 `useFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useFetch`.
 ::
 
+::LinkExample{link="/docs/examples/other/use-custom-fetch-composable"}
+::
+
 :ReadMore{link="/docs/getting-started/data-fetching"}
 
 ::LinkExample{link="/docs/examples/composables/use-fetch"}

docs/4.examples/8.other/use-custom-fetch-composable.md

@@ -0,0 +1,9 @@
+---
+toc: false
+---
+
+# Use custom fetch composable
+
+This example shows a convenient wrapper for the useFetch composable from nuxt. It allows you to customize the fetch request with default values and user authentication token.
+
+::sandbox{repo="nuxt/nuxt" branch="main" dir="examples/other/use-custom-fetch-composable" file="composables/useCustomFetch.ts"}

examples/other/use-custom-fetch-composable/app.vue

@@ -0,0 +1,16 @@
+
+<script setup lang="ts">
+
+const { data } = await useCustomFetch<object>('/beers')
+
+</script>
+
+<template>
+  <NuxtExampleLayout example="other/use-custom-fetch-composable">
+    <h1 class="text-xl opacity-50">
+      Nuxt custom fetch
+    </h1>
+
+    <pre class="text-left text-xs">{{ data }}</pre>
+  </NuxtExampleLayout>
+</template>

examples/other/use-custom-fetch-composable/composables/useCustomFetch.ts

@@ -0,0 +1,31 @@
+import type { UseFetchOptions } from 'nuxt/app'
+import { defu } from 'defu'
+
+export function useCustomFetch<T> (url: string, options: UseFetchOptions<T> = {}) {
+  const userAuth = useCookie('token')
+  const config = useRuntimeConfig()
+
+  const defaults: UseFetchOptions<T> = {
+    baseURL: config.baseUrl ?? 'https://api.nuxtjs.dev',
+    // cache request
+    key: url,
+
+    // set user token if connected
+    headers: userAuth.value
+      ? { Authorization: `Bearer ${userAuth.value}` }
+      : {},
+
+    onResponse (__ctx) {
+      // return new myBusinessResponse(response._data)
+    },
+
+    onResponseError (__ctx) {
+      // return new myBusinessError(error)
+    }
+  }
+
+  // for nice deep defaults, please use unjs/defu
+  const params = defu(defaults, options)
+
+  return useFetch(url, params)
+}

examples/other/use-custom-fetch-composable/nuxt.config.ts

@@ -0,0 +1,6 @@
+// https://nuxt.com/docs/api/configuration/nuxt-config
+export default defineNuxtConfig({
+  modules: [
+    '@nuxt/ui'
+  ]
+})

examples/other/use-custom-fetch-composable/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "example-use-custom-fetch-composable",
+  "private": true,
+  "scripts": {
+    "build": "nuxi build",
+    "dev": "nuxi dev",
+    "start": "nuxi preview"
+  },
+  "devDependencies": {
+    "@nuxt/ui": "^0.3.3",
+    "nuxt": "^3.0.0"
+  }
+}

examples/other/use-custom-fetch-composable/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  // https://nuxt.com/docs/guide/concepts/typescript
+  "extends": "./.nuxt/tsconfig.json"
+}

pnpm-lock.yaml

@@ -310,6 +310,15 @@ importers:
         specifier: workspace:*
         version: link:../../../packages/nuxt
 
+  examples/other/use-custom-fetch-composable:
+    devDependencies:
+      '@nuxt/ui':
+        specifier: ^0.3.3
+        version: 0.3.3(nuxt@packages+nuxt)(rollup@3.21.0)(vite@3.2.5)(vue@3.2.47)(webpack@5.80.0)
+      nuxt:
+        specifier: workspace:*
+        version: link:../../../packages/nuxt
+
   examples/routing/layouts:
     devDependencies:
       '@nuxt/ui':