Which Fetch? A One Page Reference for Nuxt Data Fetching

Choose among Nuxt’s $fetch, useFetch, useAsyncData, and lazy variants based on rendering, interaction, and data needs, while avoiding common pitfalls with keys, caching, SSR, and payloads.

1. Ask these first

Work down the list and stop at the first yes.

Is it a user action or a side effect (submitting, deleting, clicking)?

Use $fetch in the handler. There is no render to wait for.

Does it need to be in the HTML on first paint, for SEO or to avoid a loading flash?

useFetch if the source is a URL. useAsyncData if it is an SDK, a DB, or several calls composed together.

Can the page render before this data arrives?

Use useLazyFetch or useLazyAsyncData, then handle the loading state in the template.

Is it browser only, user specific, and not needed for SEO?

Add server: false to whichever you picked above.

Are you already inside a handler, a server route, or a plugin?

Use $fetch. Never nest one data composable inside another.

2. The four tools

	What it is	SSR	Deduped by key	In payload
`useFetch(url, opts)`	`useAsyncData` plus `$fetch`, auto key	Yes	Yes	Yes
`useAsyncData(key, fn, opts)`	Wraps any async function	Yes	Yes	Yes
`useLazy*` variants	Same, with `lazy: true`	Yes, non blocking	Yes	Yes
`$fetch(url, opts)`	Configured `ofetch` instance	Only where called	No	No, refetches on hydration

During SSR, $fetch to your own /api/* hits the handler directly, no HTTP roundtrip.

3. Options

Option	Default	Notes
`key`	auto for `useFetch`	Cache and dedup identity. Required for `useAsyncData`
`server`	`true`	`false` skips SSR
`lazy`	`false`	`true` does not block navigation
`immediate`	`true`	`false` waits for `execute()`
`watch`	reactive opts	Array of sources, or `false` to opt out
`transform`	none	Reshapes before caching. Shrinks the payload
`pick`	none	Keeps listed top level keys
`default`	`null`	Give it `[]` or `{}` to skip null guards
`dedupe`	`cancel`	`defer` keeps the first call instead
`deep`	`false`	`data` is a shallow ref. `true` only if you mutate nested props
`getCachedData`	payload reuse	Reuses on hydration and client nav, not on manual `refresh()`

4. Returns

const { data, status, error, refresh, execute, clear } = await useFetch('/api/products')


`data`	Result, or `default` until resolved
`status`	`idle`, `pending`, `success`, `error`. Branch on this, not on `data`
`error`	Thrown error, resets to `null` on successful retry
`refresh()`	Refetch, keeps current data visible
`execute()`	For `immediate: false`
`clear()`	Resets state for that key

await is optional. The server waits before rendering either way.

5. Factories

Export from composables/. Both are compiler macros, so Nuxt injects dedup keys at build time.

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

const { data: profile } = await useAPI('/me')

Function form when defaults need composables or runtime config:

export const useApiFetch = createUseFetch(callerOptions => ({
  ...callerOptions,
  baseURL: callerOptions.baseURL ?? useRuntimeConfig().public.baseApiUrl,
}))

createUseAsyncData works the same way. Best home for a shared getCachedData policy.
You cannot name your own composable useFetch. Reserved and compiler transformed.

6. Refetch and cancel

Reactive URL or options refetch on their own. A computed, ref, or getter is enough.
signal from an AbortController for manual cancellation.
Default dedupe already cancels the in flight request for the same key.
clearNuxtData(key) drops the cache so the next mount refetches. Use after a mutation.

7. What usually breaks

Bare $fetch in <script setup> fetches twice. Nothing enters the payload.
Nested data composables break context and key generation. Use $fetch inside handlers.
Auto keys collide when URL and options look identical, usually in a v-for. Pass key.
Dynamic route params must be in the key, or /products/1 and /products/2 share stale data.
transform does not run on a cached read. What was cached is already transformed.
Big responses are serialized into the HTML. Use pick or transform.
data returning a string means an accidental import { useFetch } from '@vueuse/core'.
Call these in setup, a plugin, or route middleware. After an await in setup, context is lost.

8. Changing in Nuxt 5

Testable now with future.compatibilityVersion: 5.

clear() and clearNuxtData() restore your default instead of setting data to undefined.
clearNuxtState() resets to the useState init value, matching clearNuxtData.