createUseFetch

createUseFetch creates a custom useFetch 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, with all options available for the caller to use or override.

Type#

```ts [Signature] function createUseFetch ( options?: Partial, ): typeof useFetch

function createUseFetch ( options: (callerOptions: UseFetchOptions) => Partial, ): 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,
})

// 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(callerOptions => ({
  $fetch: useNuxtApp().$api as typeof $fetch,
  ...callerOptions,
}))

::important The function signature (override mode) is required here so that useNuxtApp() is called in the setup context (at the composable call site) rather than in the module scope, where no Nuxt instance is available. ::

:read-more{to="/docs/4.x/guide/recipes/custom-usefetch"}

:read-more{to="/docs/4.x/api/composables/use-fetch"}