@nuxt/docs-nightly 5.0.0-29841017.b1cd49dc → 5.0.0-29841042.d5a56a2a

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

@@ -1,7 +1,7 @@
 ---
 title: 'createUseAsyncData'
 description: A factory function to create a custom useAsyncData composable with pre-defined default options.
-minimalVersion: "4.2"
+minimalVersion: "4.4"
 links:
   - label: Source
     icon: i-simple-icons-github
@@ -40,7 +40,7 @@ The resulting composable has the same signature and return type as [`useAsyncDat
 
 ```ts [Signature]
 function createUseAsyncData (
-  options?: Partial<AsyncDataOptions>,
+  options?: Partial<AsyncDataOptions> & { addons?: UseAsyncDataAddon[] },
 ): typeof useAsyncData
 
 function createUseAsyncData (
@@ -48,6 +48,8 @@ function createUseAsyncData (
 ): typeof useAsyncData
 ```
 
+The returned composable's signature includes any custom options and return-value extensions contributed by the [addons](#addons).
+
 ## Options
 
 `createUseAsyncData` accepts all the same options as [`useAsyncData`](/docs/api/composables/use-async-data#parameters), including `server`, `lazy`, `immediate`, `default`, `transform`, `pick`, `getCachedData`, `deep`, `dedupe`, `timeout`, and `watch`.
@@ -86,6 +88,47 @@ export const useStrictData = createUseAsyncData(callerOptions => ({
 }))
 ```
 
+## Addons
+
+In addition to `useAsyncData` options, `createUseAsyncData` accepts an `addons` array. Addons are reusable units of behavior defined with [`defineUseAsyncDataAddon`](/docs/api/utils/define-use-async-data-addon). They can declare custom call-site options, run middleware around the handler, extend the returned object, and attach custom logic to the composable.
+
+For example, an addon that refreshes the data whenever the window regains focus, gated behind a custom `refreshOnFocus` option, so callers opt in per call:
+
+```ts [app/composables/useCustomAsyncData.ts]
+const refreshOnFocus = defineUseAsyncDataAddon({
+  // augment the call-site options for the custom useAsyncData instance 👇
+  setup: (options: UseAsyncDataAddonOptions<{ refreshOnFocus?: boolean }>) => {
+    // 👈 run code *before* creating the `useAsyncData` instance
+    if (import.meta.server || !options.refreshOnFocus) { return }
+
+    return (asyncData) => {
+      // 👈 run code *after* creating the `useAsyncData` instance
+      const focused = useWindowFocus()
+      watch(focused, (focused) => {
+        if (focused) { asyncData.refresh() }
+      })
+
+      return { focused } // 👈 extend the returned object with a new property
+    }
+  },
+})
+
+export const useCustomAsyncData = createUseAsyncData({ addons: [refreshOnFocus] })
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+// `refreshOnFocus` is typed on the created composable
+const { data } = await useCustomAsyncData(
+  'mountains',
+  () => $fetch('https://api.nuxtjs.dev/mountains'),
+  { refreshOnFocus: true },
+)
+</script>
+```
+
+:read-more{to="/docs/api/utils/define-use-async-data-addon"}
+
 :read-more{to="/docs/guide/recipes/custom-usefetch"}
 
 :read-more{to="/docs/api/composables/use-async-data"}

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

@@ -1,7 +1,7 @@
 ---
 title: 'createUseFetch'
 description: A factory function to create a custom useFetch composable with pre-defined default options.
-minimalVersion: "4.2"
+minimalVersion: "4.4"
 links:
   - label: Source
     icon: i-simple-icons-github
@@ -35,7 +35,7 @@ The resulting `useAPI` composable has the same signature and return type as [`us
 
 ```ts [Signature]
 function createUseFetch (
-  options?: Partial<UseFetchOptions>,
+  options?: Partial<UseFetchOptions> & { addons?: UseFetchAddon[] },
 ): typeof useFetch
 
 function createUseFetch (
@@ -44,10 +44,12 @@ function createUseFetch (
 
 // where the client declares the routes it serves
 function createUseFetch<Routes> (
-  options: Partial<UseFetchOptions> & { routes: Routes },
+  options: Partial<UseFetchOptions> & { routes: Routes, addons?: UseFetchAddon[] },
 ): DeclaredUseFetch<Routes>
 ```
 
+The returned composable's signature includes any custom options and return-value extensions contributed by the [addons](#addons).
+
 ## Options
 
 `createUseFetch` accepts all the same options as [`useFetch`](/docs/api/composables/use-fetch#parameters), including `baseURL`, `headers`, `query`, `onRequest`, `onResponse`, `server`, `lazy`, `transform`, `getCachedData`, and more.
@@ -164,6 +166,46 @@ export const useAPI = createUseFetch(callerOptions => ({
 The **function signature** (override mode) is required here so that [`useNuxtApp()`](/docs/api/composables/use-nuxt-app) is called in the setup context (at the composable call site) rather than in the module scope, where no Nuxt instance is available.
 ::
 
+## Addons
+
+In addition to `useFetch` options, `createUseFetch` accepts an `addons` array. Addons are reusable units of behavior defined with [`defineUseFetchAddon`](/docs/api/utils/define-use-fetch-addon). They can declare custom call-site options, run middleware around the handler, extend the returned object, and attach custom logic to the composable.
+
+For example, an addon that refreshes the data whenever the window regains focus, gated behind a custom `refreshOnFocus` option, so callers opt in per call:
+
+```ts [app/composables/useCustomFetch.ts]
+const refreshOnFocus = defineUseFetchAddon({
+  // augment the call-site options for the custom useFetch instance 👇
+  setup: (options: UseFetchAddonOptions<{ refreshOnFocus?: boolean }>) => {
+    // 👈 run code *before* calling `useAsyncData` in `useFetch`
+    if (import.meta.server || !options.refreshOnFocus) { return }
+
+    return (asyncData) => {
+      // 👈 run code *after* calling `useAsyncData` in `useFetch`
+      const focused = useWindowFocus()
+      watch(focused, (focused) => {
+        if (focused) { asyncData.refresh() }
+      })
+
+      return { focused } // 👈 extend the returned object with a new property
+    }
+  },
+})
+
+export const useCustomFetch = createUseFetch({ addons: [refreshOnFocus] })
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+// `refreshOnFocus` is typed on the created composable
+const { data } = await useCustomFetch(
+  'https://api.nuxtjs.dev/mountains',
+  { refreshOnFocus: true },
+)
+</script>
+```
+
+:read-more{to="/docs/api/utils/define-use-fetch-addon"}
+
 :read-more{to="/docs/guide/recipes/custom-usefetch"}
 
 :read-more{to="/docs/api/composables/use-fetch"}

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

@@ -168,8 +168,11 @@ type AsyncDataOptions<ResT, DataT = ResT> = {
   timeout?: number
   enabled?: MaybeRefOrGetter<boolean>
   serialize?: boolean
+  middleware?: AsyncDataMiddleware<ResT>[]
 }
 
+type AsyncDataMiddleware<ResT> = (next: () => Promise<ResT>, ctx: { signal: AbortSignal }) => Promise<ResT>
+
 type AsyncDataRequestContext = {
   /** The reason for this data request */
   cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
@@ -220,6 +223,7 @@ The `handler` function should be **side-effect free** to ensure predictable beha
 | `dedupe` :badge[v3.9]{color="info" size="xs" class="align-middle"}        | `'cancel' \| 'defer'`                       | `'cancel'` | Policy when triggering an execution more than once at a time.                                                                                                                                                                                                                        |
 | `enabled` :badge[v4.5]{color="info" size="xs" class="align-middle"}       | `boolean`                                   | `true`     | Barrier that gates whether the `handler` may run. While `false`, every execution is blocked (initial fetch, `execute`/`refresh`, and watch triggers), and switching `true` → `false` cancels any in-flight request without clearing `data`. Re-enabling does not refetch on its own. |
 | `serialize` :badge[v4.6]{color="info" size="xs" class="align-middle"}     | `boolean`                                   | `true`     | Whether to store resolved data in the Nuxt payload (`__NUXT_DATA__`). When `false`, server-fetched data is kept out of the payload and the client will refetch after hydration if a component renders it. Pair with [lazy hydration](/docs/guide/best-practices/performance#lazy-hydration) to avoid hydration mismatches and unnecessary client fetches. |
+| `middleware` :badge[v4.6]{color="info" size="xs" class="align-middle"}    | `AsyncDataMiddleware[]`                     | -          | Functions wrapping the execution of the `handler`. Each receives `next`, which runs the rest of the chain and resolves to the data, and the handler context (`{ signal }`). The first entry is the outermost wrapper. Call `next()` to continue or throw to abort. |
 
 ::note
 All options can be given a `computed` or `ref` value. These will be watched and new requests made automatically with any new values if they are updated.
@@ -255,6 +259,7 @@ The following options **must be consistent** across all calls with the same key:
 - `pick` array
 - `getCachedData` function
 - `default` value
+- `middleware` array
 
 The following options **can differ** without triggering warnings:
 - `server`

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

@@ -177,6 +177,7 @@ type UseFetchOptions<ResT, DataT = ResT> = {
   timeout?: number
   enabled?: MaybeRefOrGetter<boolean>
   serialize?: boolean
+  middleware?: AsyncDataMiddleware<ResT>[]
   default?: () => DataT | Ref<DataT>
   transform?: (input: ResT) => DataT | Promise<DataT>
   pick?: string[]
@@ -236,6 +237,7 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 | `dedupe` :badge[v3.9]{color="info" size="xs" class="align-middle"}        | `'cancel' \| 'defer'`                                                   | `'cancel'` | Avoid fetching same key more than once at a time.                                                                                                                                                                                                                                  |
 | `enabled` :badge[v4.5]{color="info" size="xs" class="align-middle"}       | `boolean`                                                               | `true`     | Barrier that gates whether the request may run. While `false`, every execution is blocked (initial fetch, `execute`/`refresh`, and watch triggers), and switching `true` → `false` cancels any in-flight request without clearing `data`. Re-enabling does not refetch on its own. |
 | `serialize` :badge[v4.6]{color="info" size="xs" class="align-middle"}     | `boolean`                                                               | `true`     | Whether to store resolved data in the Nuxt payload (`__NUXT_DATA__`). When `false`, server-fetched data is kept out of the payload and the client will refetch after hydration if a component renders it. Pair with [lazy hydration](/docs/guide/best-practices/performance#lazy-hydration) to avoid hydration mismatches and unnecessary client fetches. |
+| `middleware` :badge[v4.6]{color="info" size="xs" class="align-middle"}    | `AsyncDataMiddleware[]`                                                 | -          | Functions wrapping the execution of the request. Each receives `next`, which runs the rest of the chain and resolves to the data, and the handler context (`{ signal }`). The first entry is the outermost wrapper. Call `next()` to continue or throw to abort. |
 | `$fetch` :badge[v3.2]{color="info" size="xs" class="align-middle"}        | `typeof globalThis.$fetch`                                              | -          | Custom $fetch implementation. See [Custom useFetch in Nuxt](/docs/guide/recipes/custom-usefetch)                                                                                                                                                                               |
 
 ::note

package/4.api/3.utils/define-use-async-data-addon.md

@@ -0,0 +1,57 @@
+---
+title: 'defineUseAsyncDataAddon'
+description: Define a reusable addon that extends composables created with createUseAsyncData.
+minimalVersion: "4.6"
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/addons.ts
+    size: xs
+---
+
+`defineUseAsyncDataAddon` defines a reusable extension for `useAsyncData` composables created with [`createUseAsyncData`](/docs/api/composables/create-use-async-data).
+
+An addon can declare custom call-site options, wrap the handler with middleware, attach custom reactive logic or extend the returned object.
+
+:read-more{to="/docs/api/utils/define-use-fetch-addon" title="defineUseFetchAddon: Addons for useAsyncData work the same way as useFetch addons"}
+
+## Usage
+
+For example, an addon adding a `pollEvery` option that refreshes the data on an interval:
+
+```ts [app/composables/usePolledAsyncData.ts]
+const polling = defineUseAsyncDataAddon({
+  setup: (options: UseAsyncDataAddonOptions<{ pollEvery?: number }>) => {
+    if (import.meta.server || !options.pollEvery) { return }
+    return (asyncData) => {
+      const interval = setInterval(() => asyncData.refresh(), options.pollEvery)
+      onScopeDispose(() => clearInterval(interval))
+    }
+  },
+})
+
+export const usePolledAsyncData = createUseAsyncData({ addons: [polling] })
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+// refreshes the data every 30 seconds
+const { data } = await usePolledAsyncData(
+  'mountains',
+  () => $fetch('https://api.nuxtjs.dev/mountains'),
+  { pollEvery: 30_000 },
+)
+</script>
+```
+
+::note
+Addons run in the order of the `addons` array, with middleware from the first addon as the outermost wrapper. Listing the same addon object more than once runs it only once.
+::
+
+## Type
+
+```ts [Signature]
+function defineUseAsyncDataAddon<Opts extends Record<string, any> = {}, Ext = {}> (addon: {
+  setup: (options: UseAsyncDataAddonOptions<Opts>) => ((asyncData: AsyncDataAddonInstance) => Ext | void) | void
+}): UseAsyncDataAddon<Opts, Ext>
+```

package/4.api/3.utils/define-use-fetch-addon.md

@@ -0,0 +1,168 @@
+---
+title: 'defineUseFetchAddon'
+description: Define a reusable addon that extends composables created with createUseFetch.
+minimalVersion: "4.6"
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/addons.ts
+    size: xs
+---
+
+`defineUseFetchAddon` defines a reusable extension for `useFetch` composables created with [`createUseFetch`](/docs/api/composables/create-use-fetch).
+
+An addon can declare custom call-site options, wrap the handler with middleware, attach custom reactive logic or extend the returned object.
+
+## Usage
+
+Pass addons to `createUseFetch` via the `addons` array.
+
+This addon attaches custom logic: a watcher that refreshes the data whenever the window regains focus and gates it behind a custom `refreshOnFocus` option:
+
+```ts [app/composables/useCustomFetch.ts]
+const refreshOnFocus = defineUseFetchAddon({
+  // augment the call-site options for the custom useFetch instance 👇
+  setup: (options: UseFetchAddonOptions<{ refreshOnFocus?: boolean }>) => {
+    // 👈 run code *before* calling `useAsyncData` in `useFetch`
+    if (import.meta.server || !options.refreshOnFocus) { return }
+
+    return (asyncData) => {
+      // 👈 run code *after* calling `useAsyncData` in `useFetch`
+      const focused = useWindowFocus()
+      watch(focused, (focused) => {
+        if (focused) { asyncData.refresh() }
+      })
+
+      return { focused } // 👈 extend the returned object with a new property
+    }
+  },
+})
+
+export const useCustomFetch = createUseFetch({ addons: [refreshOnFocus] })
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+const { data } = await useCustomFetch('/some-endpoint', { refreshOnFocus: true })
+</script>
+```
+
+The addon's `setup` function runs on every call of the composable, and receives the merged options (factory defaults plus caller options).
+
+::note
+Addons run in the order of the `addons` array, with middleware from the first addon as the outermost wrapper. Listing the same addon object more than once runs it only once.
+::
+
+## Custom Options
+
+Declare custom options by annotating the `setup` `options` parameter with `UseFetchAddonOptions<{ ... }>`. The options become part of the created composable's signature, fully typed for callers:
+
+```ts [app/composables/useCustomFetch.ts]
+const auth = defineUseFetchAddon({
+  setup: (options: UseFetchAddonOptions<{ auth?: MaybeRefOrGetter<boolean> }>) => {
+    const { token } = useTokenStore()
+    options.auth ??= true
+    options.onRequest.push(({ options: fetchOptions }) => {
+      if (!toValue(options.auth)) { return }
+      fetchOptions.headers.set('Authorization', `Bearer ${token.value}`)
+    })
+  },
+})
+
+export const useCustomFetch = createUseFetch({ addons: [auth] })
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+// `auth` is typed
+const { data } = await useCustomFetch('/public-endpoint', { auth: false })
+</script>
+```
+
+Custom options stay in the merged options object, so they are also passed to `$fetch` along with the request options, which ignores keys it does not recognise.
+
+## Extending the Return Value
+
+If `setup` returns a function, that function is called with the async data instance. Any object it returns is merged into the composable's return value:
+
+```ts
+const timestamps = defineUseFetchAddon({
+  setup: () => {
+    const refreshedAt = ref<Date>()
+
+    return (asyncData) => {
+      watch(asyncData.status, (status) => {
+        if (status === 'success') { refreshedAt.value = new Date() }
+      }, { immediate: true })
+
+      return { refreshedAt: readonly(refreshedAt) }
+    }
+  },
+})
+
+export const useCustomFetch = createUseFetch({ addons: [timestamps] })
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+// `refreshedAt` is typed
+const { data, refreshedAt } = await useCustomFetch('/modules')
+</script>
+```
+
+## Middleware
+
+Middleware wraps the execution of the request handler. Call `next()` to continue the chain (and get the resolved data), or throw to abort. Middleware from the first addon is the outermost wrapper:
+
+```ts
+const minDuration = defineUseFetchAddon({
+  setup: (options: UseFetchAddonOptions<{ minDuration?: number }>) => {
+    options.middleware.push(async (next) => {
+      const [result] = await Promise.all([
+        next(),
+        new Promise(resolve => setTimeout(resolve, toValue(options.minDuration) ?? 300)),
+      ])
+      return result
+    })
+  },
+})
+```
+
+## Contributing to the Auto-Generated Key
+
+Custom options are **not** part of the auto-generated key by default. If a custom option affects the response, provide a `key` resolver so calls with different values do not share a cached entry. Return a serializable value, or `undefined` to contribute nothing:
+
+```ts
+const scoped = defineUseFetchAddon({
+  setup: (options: UseFetchAddonOptions<{ scope?: string }>) => {
+    options.scope ??= 'default'
+    // ...
+  },
+  key: options => toValue(options.scope),
+})
+```
+
+::warning
+Declare `setup` before `key`. TypeScript infers the custom options from the `setup` parameter annotation, and a `key` resolver written before a `setup` that returns an extension function is checked first and typed with empty options.
+::
+
+## Wrapping `then`, `catch` and `finally`
+
+As an advanced escape hatch, the extension object may include `then`, `catch` or `finally` functions. These are not merged into the instance. Instead they wrap the corresponding method of the awaitable promise, receiving the original method as their first argument.
+
+::note
+When several addons wrap the same method, the wrappers are composed in the order of the `addons` array: the first addon's wrapper wraps all the following ones, just as its middleware would.
+::
+
+## Type
+
+```ts [Signature]
+function defineUseFetchAddon<Opts extends Record<string, any> = {}, Ext = {}> (addon: {
+  setup: (options: UseFetchAddonOptions<Opts>) => ((asyncData: AsyncDataAddonInstance) => Ext | void) | void
+  key?: (options: UseFetchAddonOptions<Opts>) => SerializableValue
+}): UseFetchAddon<Opts, Ext>
+```
+
+::note
+`middleware`, `onRequest`, `onRequestError`, `onResponse` and `onResponseError` are always normalized to arrays, so interceptors from the caller and from other addons are preserved.
+::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29841017.b1cd49dc",
+  "version": "5.0.0-29841042.d5a56a2a",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",