@nuxt/docs-nightly 4.4.0-29554618.f8e243a5 → 4.4.0-29555069.df7ef5d2

package/3.guide/5.recipes/3.custom-usefetch.md

@@ -10,19 +10,46 @@ The [`$fetch`](/docs/4.x/api/utils/dollarfetch) utility function (used by the [`
 
 However, Nuxt provides a way to create a custom fetcher for your API (or multiple fetchers if you have multiple APIs to call).
 
-## Custom `$fetch`
+## Recipe: API Client with Auth
 
-Let's create a custom `$fetch` instance with a [Nuxt plugin](/docs/4.x/directory-structure/app/plugins).
+Let's say you have an external API at `https://api.nuxt.com` that requires JWT authentication via [nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils), and you want to redirect to `/login` on `401` responses.
+
+```ts [app/composables/useAPI.ts]
+export const useAPI = createUseFetch({
+  baseURL: 'https://api.nuxt.com',
+  onRequest ({ options }) {
+    const { session } = useUserSession()
+    if (session.value?.token) {
+      options.headers.set('Authorization', `Bearer ${session.value.token}`)
+    }
+  },
+  async onResponseError ({ response }) {
+    if (response.status === 401) {
+      await navigateTo('/login')
+    }
+  },
+})
+```
+
+Now every call to `useAPI` automatically includes the auth header and handles 401 redirects:
+
+```vue [app/pages/dashboard.vue]
+<script setup lang="ts">
+const { data: profile } = await useAPI('/me')
+const { data: orders } = await useAPI('/orders')
+</script>
+```
+
+:read-more{to="/docs/4.x/api/composables/create-use-fetch"}
+
+## Recipe: Custom `$fetch` Instance
+
+If you need lower-level control, you can create a custom `$fetch` instance with a [Nuxt plugin](/docs/4.x/directory-structure/app/plugins) and either use it with `useAsyncData` directly or pass it to `createUseFetch`.
 
 ::note
 `$fetch` is a configured instance of [ofetch](https://github.com/unjs/ofetch) which supports adding the base URL of your Nuxt server as well as direct function calls during SSR (avoiding HTTP roundtrips).
 ::
 
-Let's pretend here that:
-- The main API is https://api.nuxt.com
-- We are storing the JWT token in a session with [nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils)
-- If the API responds with a `401` status code, we redirect the user to the `/login` page
-
 ```ts [app/plugins/api.ts]
 export default defineNuxtPlugin((nuxtApp) => {
   const { session } = useUserSession()
@@ -31,7 +58,6 @@ export default defineNuxtPlugin((nuxtApp) => {
     baseURL: 'https://api.nuxt.com',
     onRequest ({ request, options, error }) {
       if (session.value?.token) {
-        // note that this relies on ofetch >= 1.4.0 - you may need to refresh your lockfile
         options.headers.set('Authorization', `Bearer ${session.value?.token}`)
       }
     },
@@ -42,7 +68,6 @@ export default defineNuxtPlugin((nuxtApp) => {
     },
   })
 
-  // Expose to useNuxtApp().$api
   return {
     provide: {
       api,
@@ -51,7 +76,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 })
 ```
 
-With this Nuxt plugin, `$api` is exposed from `useNuxtApp()` to make API calls directly from the Vue components:
+You can then use the custom `$fetch` instance directly:
 
 ```vue [app/app.vue]
 <script setup>
@@ -61,65 +86,9 @@ const { data: modules } = await useAsyncData('modules', () => $api('/modules'))
 ```
 
 ::callout
-Wrapping with [`useAsyncData`](/docs/4.x/api/composables/use-async-data) **avoid double data fetching when doing server-side rendering** (server & client on hydration).
-::
-
-## Custom `useFetch`/`useAsyncData`
-
-Now that `$api` has the logic we want, let's create a `useAPI` composable to replace the usage of `useAsyncData` + `$api`:
-
-```ts [app/composables/useAPI.ts]
-import type { UseFetchOptions } from 'nuxt/app'
-
-export function useAPI<T> (
-  url: string | (() => string),
-  options?: UseFetchOptions<T>,
-) {
-  return useFetch(url, {
-    ...options,
-    $fetch: useNuxtApp().$api as typeof $fetch,
-  })
-}
-```
-
-Let's use the new composable and have a nice and clean component:
-
-```vue [app/app.vue]
-<script setup>
-const { data: modules } = await useAPI('/modules')
-</script>
-```
-
-If you want to customize the type of any error returned, you can also do so:
-
-```ts
-import type { FetchError } from 'ofetch'
-import type { UseFetchOptions } from 'nuxt/app'
-
-interface CustomError {
-  message: string
-  status: number
-}
-
-export function useAPI<T> (
-  url: string | (() => string),
-  options?: UseFetchOptions<T>,
-) {
-  return useFetch<T, FetchError<CustomError>>(url, {
-    ...options,
-    $fetch: useNuxtApp().$api,
-  })
-}
-```
-
-::note
-This example demonstrates how to use a custom `useFetch`, but the same structure is identical for a custom `useAsyncData`.
+Wrapping with [`useAsyncData`](/docs/4.x/api/composables/use-async-data) **avoids double data fetching when doing server-side rendering** (server & client on hydration).
 ::
 
 :link-example{to="/docs/4.x/examples/advanced/use-custom-fetch-composable"}
 
 :video-accordion{title="Watch a video about custom $fetch and Repository Pattern in Nuxt" videoId="jXH8Tr-exhI"}
-
-::note
-We are currently discussing to find a cleaner way to let you create a custom fetcher, see https://github.com/nuxt/nuxt/issues/14736.
-::

package/4.api/2.composables/create-use-async-data.md

@@ -0,0 +1,90 @@
+---
+title: 'createUseAsyncData'
+description: A factory function to create a custom useAsyncData composable with pre-defined default options.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/asyncData.ts
+    size: xs
+---
+
+`createUseAsyncData` creates a custom [`useAsyncData`](/docs/4.x/api/composables/use-async-data) composable with pre-defined options. The resulting composable is fully typed and works exactly like `useAsyncData`, but with your defaults baked in.
+
+::note
+`createUseAsyncData` is a compiler macro. It must be used as an **exported** declaration in the `composables/` directory (or any directory scanned by the Nuxt compiler). Nuxt automatically injects de-duplication keys at build time.
+::
+
+## Usage
+
+```ts [app/composables/useCachedData.ts]
+export const useCachedData = createUseAsyncData({
+  getCachedData (key, nuxtApp) {
+    return nuxtApp.payload.data[key] ?? nuxtApp.static.data[key]
+  },
+})
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+const { data: mountains } = await useCachedData(
+  'mountains',
+  () => $fetch('https://api.nuxtjs.dev/mountains'),
+)
+</script>
+```
+
+The resulting composable has the same signature and return type as [`useAsyncData`](/docs/4.x/api/composables/use-async-data), with all options available for the caller to use or override.
+
+## Type
+
+```ts [Signature]
+function createUseAsyncData (
+  options?: Partial<AsyncDataOptions>,
+): typeof useAsyncData
+
+function createUseAsyncData (
+  options: (callerOptions: AsyncDataOptions) => Partial<AsyncDataOptions>,
+): typeof useAsyncData
+```
+
+## Options
+
+`createUseAsyncData` accepts all the same options as [`useAsyncData`](/docs/4.x/api/composables/use-async-data#params), including `server`, `lazy`, `immediate`, `default`, `transform`, `pick`, `getCachedData`, `deep`, `dedupe`, `timeout`, and `watch`.
+
+See the full list of options in the [`useAsyncData` documentation](/docs/4.x/api/composables/use-async-data#params).
+
+## Default vs Override Mode
+
+### Default Mode (plain object)
+
+When you pass a plain object, the factory options act as **defaults**. Callers can override any option:
+
+```ts [app/composables/useLazyData.ts]
+export const useLazyData = createUseAsyncData({
+  lazy: true,
+  server: false,
+})
+```
+
+```ts
+// Uses the defaults (lazy: true, server: false)
+const { data } = await useLazyData('key', () => fetchSomeData())
+
+// Caller overrides server to true
+const { data } = await useLazyData('key', () => fetchSomeData(), { server: true })
+```
+
+### Override Mode (function)
+
+When you pass a function, the factory options **override** the caller's options. The function receives the caller's options as its argument:
+
+```ts [app/composables/useStrictData.ts]
+// deep is always enforced as false
+export const useStrictData = createUseAsyncData(callerOptions => ({
+  deep: false,
+}))
+```
+
+:read-more{to="/docs/4.x/guide/recipes/custom-usefetch"}
+
+:read-more{to="/docs/4.x/api/composables/use-async-data"}

package/4.api/2.composables/create-use-fetch.md

@@ -0,0 +1,97 @@
+---
+title: 'createUseFetch'
+description: A factory function to create a custom useFetch composable with pre-defined default options.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/fetch.ts
+    size: xs
+---
+
+`createUseFetch` creates a custom [`useFetch`](/docs/4.x/api/composables/use-fetch) composable with pre-defined options. The resulting composable is fully typed and works exactly like `useFetch`, but with your defaults baked in.
+
+::note
+`createUseFetch` is a compiler macro. It must be used as an **exported** declaration in the `composables/` directory (or any directory scanned by the Nuxt compiler). Nuxt automatically injects de-duplication keys at build time.
+::
+
+## Usage
+
+```ts [app/composables/useAPI.ts]
+export const useAPI = createUseFetch({
+  baseURL: 'https://api.nuxt.com',
+})
+```
+
+```vue [app/pages/modules.vue]
+<script setup lang="ts">
+const { data: modules } = await useAPI('/modules')
+</script>
+```
+
+The resulting `useAPI` composable has the same signature and return type as [`useFetch`](/docs/4.x/api/composables/use-fetch), with all options available for the caller to use or override.
+
+## Type
+
+```ts [Signature]
+function createUseFetch (
+  options?: Partial<UseFetchOptions>,
+): typeof useFetch
+
+function createUseFetch (
+  options: (callerOptions: UseFetchOptions) => Partial<UseFetchOptions>,
+): typeof useFetch
+```
+
+## Options
+
+`createUseFetch` accepts all the same options as [`useFetch`](/docs/4.x/api/composables/use-fetch#parameters), including `baseURL`, `headers`, `query`, `onRequest`, `onResponse`, `server`, `lazy`, `transform`, `getCachedData`, and more.
+
+See the full list of options in the [`useFetch` documentation](/docs/4.x/api/composables/use-fetch#parameters).
+
+## Default vs Override Mode
+
+### Default Mode (plain object)
+
+When you pass a plain object, the factory options act as **defaults**. Callers can override any option:
+
+```ts [app/composables/useAPI.ts]
+export const useAPI = createUseFetch({
+  baseURL: 'https://api.nuxt.com',
+  lazy: true,
+})
+```
+
+```ts
+// Uses the default baseURL
+const { data } = await useAPI('/modules')
+
+// Caller overrides the baseURL
+const { data } = await useAPI('/modules', { baseURL: 'https://other-api.com' })
+```
+
+### Override Mode (function)
+
+When you pass a function, the factory options **override** the caller's options. The function receives the caller's options as its argument, so you can read them to compute your overrides:
+
+```ts [app/composables/useAPI.ts]
+// baseURL is always enforced, regardless of what the caller passes
+export const useAPI = createUseFetch(callerOptions => ({
+  baseURL: 'https://api.nuxt.com',
+}))
+```
+
+This is useful for enforcing settings like authentication headers or a specific base URL that should not be changed by the caller.
+
+## Combining with a Custom `$fetch`
+
+You can pass a custom `$fetch` instance to `createUseFetch`:
+
+```ts [app/composables/useAPI.ts]
+export const useAPI = createUseFetch({
+  $fetch: useNuxtApp().$api as typeof $fetch,
+})
+```
+
+:read-more{to="/docs/4.x/guide/recipes/custom-usefetch"}
+
+:read-more{to="/docs/4.x/api/composables/use-fetch"}

package/4.api/2.composables/use-async-data.md

@@ -25,8 +25,8 @@ const { data, status, pending, error, refresh, clear } = await useAsyncData(
 </script>
 ```
 
-::warning{to="/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata"}
-If you're using a custom `useAsyncData` wrapper, do not await it in the composable as that can cause unexpected behavior. See recipe for custom async data fetcher.
+::tip{to="/docs/4.x/guide/recipes/custom-usefetch#custom-usefetch-with-createusefetch"}
+Need a custom `useAsyncData` with pre-defined defaults? Use `createUseAsyncData` to create a fully typed custom composable. See the [custom useFetch recipe](/docs/4.x/guide/recipes/custom-usefetch) for details.
 ::
 
 ::note

package/4.api/2.composables/use-fetch.md

@@ -25,8 +25,8 @@ const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
 </script>
 ```
 
-::warning{to="/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata"}
-If you're using a custom `useFetch` wrapper, do not await it in the composable as that can cause unexpected behavior. See recipe for custom async data fetcher.
+::tip{to="/docs/4.x/guide/recipes/custom-usefetch#custom-usefetch-with-createusefetch"}
+Need a custom `useFetch` with pre-defined defaults (like `baseURL` or auth headers)? Use `createUseFetch` to create a fully typed custom composable.
 ::
 
 ::note
@@ -87,7 +87,7 @@ Keyed state created using `useFetch` can be retrieved across your Nuxt applicati
 ::
 
 ::warning
-`useFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useFetch`.
+`useFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useFetch`. To create a custom variant with pre-defined options, use [`createUseFetch`](/docs/4.x/guide/recipes/custom-usefetch#custom-usefetch-with-createusefetch) instead.
 ::
 
 ::warning
@@ -151,7 +151,6 @@ type UseFetchOptions<DataT> = {
   pick?: string[]
   $fetch?: typeof globalThis.$fetch
   watch?: MultiWatchSources | false
-  timeout?: MaybeRefOrGetter<number>
 }
 
 type AsyncDataRequestContext = {
@@ -193,7 +192,6 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 | `body`          | `MaybeRefOrGetter<RequestInit['body'] \| Record<string, any>>`          | -          | Request body. Objects are automatically stringified.                                                             |
 | `headers`       | `MaybeRefOrGetter<Record<string, string> \| [key, value][] \| Headers>` | -          | Request headers.                                                                                                 |
 | `baseURL`       | `MaybeRefOrGetter<string>`                                              | -          | Base URL for the request.                                                                                        |
-| `timeout`       | `MaybeRefOrGetter<number>`                                              | -          | Timeout in milliseconds to abort the request.                                                                    |
 | `cache`         | `boolean \| string`                                                     | -          | Cache control. Boolean disables cache, or use Fetch API values: `default`, `no-store`, etc.                      |
 | `server`        | `boolean`                                                               | `true`     | Whether to fetch on the server.                                                                                  |
 | `lazy`          | `boolean`                                                               | `false`    | If true, resolves after route loads (does not block navigation).                                                 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.4.0-29554618.f8e243a5",
+  "version": "4.4.0-29555069.df7ef5d2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",