createUseFetch

Source
A factory function to create a custom useFetch composable with pre-defined default options.

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.

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

app/composables/useAPI.ts
export const useAPI = createUseFetch({
  baseURL: 'https://api.nuxt.com',
})
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

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, including baseURL, headers, query, onRequest, onResponse, server, lazy, transform, getCachedData, and more.

See the full list of options in the useFetch documentation.

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:

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:

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:

app/composables/useAPI.ts
export const useAPI = createUseFetch({
  $fetch: useNuxtApp().$api as typeof $fetch,
})
Read more in Docs > 4 X > Guide > Recipes > Custom Usefetch.
Read more in Docs > 4 X > API > Composables > Use Fetch.