@nuxt/docs 4.3.1 → 4.4.2

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/3.guide/5.recipes/4.sessions-and-authentication.md

@@ -210,7 +210,7 @@ We've successfully set up a very basic user authentication and session managemen
 
 As next steps, you can:
 - Add authentication using the [20+ supported OAuth providers](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#supported-oauth-providers)
-- Add a database to store users, see [Nitro SQL Database](https://nitro.build/guide/database) or [NuxtHub SQL Database](https://hub.nuxt.com/docs/features/database)
+- Add a database to store users, see [Nitro SQL Database](https://nitro.build/guide/database) or [NuxtHub SQL Database](https://hub.nuxt.com/docs/database)
 - Let user signup with email & password using [password hashing](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#password-hashing)
 - Add support for [WebAuthn / Passkeys](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#webauthn-passkey)
 

package/3.guide/6.going-further/1.experimental-features.md

@@ -238,12 +238,19 @@ export default defineNuxtConfig({
 
 ## payloadExtraction
 
-Enables extraction of payloads of pages generated with `nuxt generate`.
+Controls how payload data is delivered for prerendered and cached (ISR/SWR) pages.
+
+- `'client'` - Payload is inlined in HTML for the initial server render, and extracted to `_payload.json` files for client-side navigation. This avoids a separate network request on initial load while still enabling efficient client-side navigation.
+- `true` - Payload is extracted to a separate `_payload.json` file for both the initial server render and client-side navigation.
+- `false` - Payload extraction is disabled entirely. Payload is always inlined in HTML and no `_payload.json` files are generated.
+
+The default is `true`, or `'client'` when `compatibilityVersion: 5` is set.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    payloadExtraction: true,
+    // Inline payload in HTML, extract for client-side navigation only
+    payloadExtraction: 'client',
   },
 })
 ```
@@ -253,7 +260,7 @@ Payload extraction also works for routes using ISR (Incremental Static Regenerat
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    payloadExtraction: true,
+    payloadExtraction: 'client',
   },
   routeRules: {
     // Payload files will be generated for these cached routes
@@ -303,11 +310,27 @@ export default defineNuxtConfig({
 })
 ```
 
+You can also pass an object to configure [view transition types](/docs/4.x/getting-started/transitions#view-transition-types), which allow different CSS animations based on the type of navigation:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    viewTransition: {
+      enabled: true,
+      types: ['slide'],
+    },
+  },
+})
+```
+
 :link-example{to="https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue" target="_blank"}
 
 ::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API" target="_blank"}
 Read more about the **View Transition API**.
 ::
+::read-more{icon="i-simple-icons-google" to="https://developer.chrome.com/blog/view-transitions-update-io24" target="_blank"}
+Read more about the **View Transition API**.
+::
 
 ## writeEarlyHints
 
@@ -370,7 +393,11 @@ Out of the box, this will enable typed usage of [`navigateTo`](/docs/4.x/api/uti
 You can even get typed params within a page by using `const route = useRoute('route-name')`.
 
 ::important
-If you use `pnpm` without `shamefully-hoist=true`, you will need to have `unplugin-vue-router` installed as a devDependency in order for this feature to work.
+If you use `pnpm` without `shamefully-hoist=true`, you will need to add `unplugin-vue-router` as a hoist pattern in your `pnpm-workspace.yaml` in order for this feature to work.
+```yaml
+publicHoistPattern:
+  - "unplugin-vue-router"
+```
 ::
 
 :video-accordion{title="Watch a video from Daniel Roe explaining type-safe routing in Nuxt" videoId="SXk-L19gTZk"}
@@ -603,6 +630,30 @@ But in order to auto-import it, you would need to use `SomeFolderMyComponent`.
 
 By setting `experimental.normalizeComponentNames`, these two values match, and Vue will generate a component name that matches the Nuxt pattern for component naming.
 
+## normalizePageNames
+
+Ensure that page component names match their route names. This sets the `__name` property on page components so that Vue's `<KeepAlive>` can correctly identify them by name.
+
+By default, Vue assigns component names based on the filename. For example, `pages/foo/index.vue` and `pages/bar/index.vue` would both have the component name `index`. This makes name-based `<KeepAlive>` filtering unreliable because multiple pages share the same name.
+
+With `normalizePageNames` enabled, page components are named after their route (e.g. `foo` and `bar`), so you can use `<KeepAlive>` with `include`/`exclude` without manually adding `defineOptions({ name: '...' })` to each page.
+
+This flag is enabled when `future.compatibilityVersion` is set to `5` or higher, but you can disable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    normalizePageNames: false,
+  },
+})
+```
+
+```vue [app.vue]
+<template>
+  <NuxtPage :keepalive="{ include: ['foo'] }" />
+</template>
+```
+
 ## spaLoadingTemplateLocation
 
 When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `~/spa-loading-template.html`).
@@ -722,7 +773,9 @@ export default defineNuxtConfig({
 
 ## decorators
 
-This option enables enabling decorator syntax across your entire Nuxt/Nitro app, powered by [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3).
+This option enables decorator syntax across your entire Nuxt/Nitro app.
+
+When using the Vite builder (default), decorators are lowered via [Babel](https://babeljs.io/) using [`@babel/plugin-proposal-decorators`](https://babeljs.io/docs/babel-plugin-proposal-decorators). When using the webpack or rspack builders, decorators are lowered via [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3).
 
 For a long time, TypeScript has had support for decorators via `compilerOptions.experimentalDecorators`. This implementation predated the TC39 standardization process. Now, decorators are a [Stage 3 Proposal](https://github.com/tc39/proposal-decorators), and supported without special configuration in TS 5.0+ (see https://github.com/microsoft/TypeScript/pull/52582 and https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators).
 
@@ -742,6 +795,24 @@ export default defineNuxtConfig({
 })
 ```
 
+When using the Vite builder or the Nitro server build, you will need to install additional Babel packages as dev dependencies:
+
+::code-group
+```bash [npm]
+npm install -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
+```
+```bash [pnpm]
+pnpm add -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
+```
+```bash [yarn]
+yarn add -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
+```
+::
+
+::tip
+Nuxt will prompt you to install these automatically if they are not already present.
+::
+
 ```ts [app/app.vue]
 function something (_method: () => unknown) {
   return () => 'decorated'
@@ -778,11 +849,16 @@ export default defineNuxtConfig({
       useAsyncData: {
         deep: true,
       },
+      useState: {
+        resetOnClear: true,
+      },
     },
   },
 })
 ```
 
+The `useState.resetOnClear` option controls whether [`clearNuxtState`](/docs/4.x/api/utils/clear-nuxt-state) resets state to its initial value (provided by the `init` function of [`useState`](/docs/4.x/api/composables/use-state)) instead of setting it to `undefined`. This defaults to `true` with `compatibilityVersion: 5`.
+
 ## purgeCachedData
 
 Whether to clean up Nuxt static and asyncData caches on route navigation.

package/4.api/1.components/12.nuxt-route-announcer.md

@@ -52,3 +52,7 @@ To achieve full customization, you can implement your own one based on [its sour
 ::callout
 You can hook into the underlying announcer instance using [the `useRouteAnnouncer` composable](/docs/4.x/api/composables/use-route-announcer), which allows you to set a custom announcement message.
 ::
+
+::callout
+For announcing in-page content changes (form validation, toast notifications, loading states, etc.), use the [`<NuxtAnnouncer>`](/docs/4.x/api/components/nuxt-announcer) component with the [`useAnnouncer`](/docs/4.x/api/composables/use-announcer) composable instead.
+::

package/4.api/1.components/14.nuxt-announcer.md

@@ -0,0 +1,81 @@
+---
+title: '<NuxtAnnouncer>'
+description: 'The <NuxtAnnouncer> component adds a hidden element to announce dynamic content changes to assistive technologies.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-announcer.ts
+    size: xs
+---
+
+::important
+This component is available in Nuxt v3.17+.
+::
+
+## Usage
+
+Add `<NuxtAnnouncer/>` in your [`app.vue`](/docs/4.x/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) to enable announcing dynamic content changes to screen readers. This is useful for form validation, toast notifications, loading states, and other in-page updates.
+
+```vue [app/app.vue]
+<template>
+  <NuxtAnnouncer />
+  <NuxtRouteAnnouncer />
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+Then use the [`useAnnouncer`](/docs/4.x/api/composables/use-announcer) composable anywhere in your app to announce messages:
+
+```vue [app/pages/contact.vue]
+<script setup lang="ts">
+const { polite, assertive } = useAnnouncer()
+
+async function submitForm () {
+  try {
+    await $fetch('/api/contact', { method: 'POST', body: formData })
+    polite('Message sent successfully')
+  } catch (error) {
+    assertive('Error: Failed to send message')
+  }
+}
+</script>
+```
+
+## Slots
+
+You can pass custom HTML or components through the announcer's default slot.
+
+```vue
+<template>
+  <NuxtAnnouncer>
+    <template #default="{ message }">
+      <p>{{ message }}</p>
+    </template>
+  </NuxtAnnouncer>
+</template>
+```
+
+## Props
+
+- `atomic`: Controls if screen readers announce only changes or the entire content. Set to true for full content readouts on updates, false for changes only. (default `true`)
+- `politeness`: Sets the default urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately). (default `polite`)
+
+## Differences from `<NuxtRouteAnnouncer>`
+
+| Aspect | `<NuxtRouteAnnouncer>` | `<NuxtAnnouncer>` |
+|--------|------------------------|-------------------|
+| **Purpose** | Announces route/page changes | Announces any dynamic content |
+| **Trigger** | Automatic on navigation | Manual via `polite()`/`assertive()` |
+| **Message source** | Page `<title>` | Developer-provided |
+| **atomic default** | `false` | `true` |
+
+::callout
+This component is optional. :br
+To achieve full customization, you can implement your own one based on [its source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-announcer.ts).
+::
+
+::callout
+You can hook into the underlying announcer instance using [the `useAnnouncer` composable](/docs/4.x/api/composables/use-announcer), which allows you to set custom announcement messages.
+::

package/4.api/1.components/3.nuxt-layout.md

@@ -86,6 +86,35 @@ console.log(layoutCustomProps.title) // I am a custom layout
 </script>
 ```
 
+## Layout Props from Page Meta
+
+When using [`definePageMeta`](/docs/4.x/api/utils/define-page-meta) with the object syntax for `layout`, props are automatically passed to the layout component. The layout can receive them with `defineProps`:
+
+```vue [app/pages/dashboard.vue]
+<script setup lang="ts">
+definePageMeta({
+  layout: {
+    name: 'admin',
+    props: {
+      sidebar: true,
+    },
+  },
+})
+</script>
+```
+
+```vue [app/layouts/admin.vue]
+<script setup lang="ts">
+const props = defineProps<{
+  sidebar?: boolean
+}>()
+</script>
+```
+
+::read-more{to="/docs/4.x/directory-structure/app/layouts#passing-props-to-layouts"}
+Read more about passing props to layouts.
+::
+
 ## Transitions
 
 `<NuxtLayout />` renders incoming content via `<slot />`, which is then wrapped around Vue’s `<Transition />` component to activate layout transition. For this to work as expected, it is recommended that `<NuxtLayout />` is **not** the root element of the page component.

package/4.api/1.components/8.nuxt-island.md

@@ -74,4 +74,4 @@ Some slots are reserved to `NuxtIsland` for special cases.
   - **parameters**:
     - **error**:
       - **type**: `unknown`
-  - **description**: emitted when when `NuxtIsland` fails to fetch the new island.
+  - **description**: emitted when `NuxtIsland` fails to fetch the new island.

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"}