Skip to content

Migrate to tanstack-fetch ​

tanstack-fetch matches TanStack Query: return data, throw FetchError, honor AbortSignal.

CLI ​

bash
npm install tanstack-fetch

# Health-check before migrating
npx tanstack-fetch doctor --dir ./src
# alias:
npx tanstack-fetch --doctor --dir ./src

# Scan (dry run)
npx tanstack-fetch migrate --from axios --dir ./src
npx tanstack-fetch migrate --from ky --dir ./src
npx tanstack-fetch migrate --from ofetch --dir ./src
npx tanstack-fetch migrate --from fetch --dir ./src
npx tanstack-fetch migrate --from all --dir ./src

# Apply safe transforms + framework scaffold
npx tanstack-fetch migrate --from axios --framework react --dir ./src --write
npx tanstack-fetch migrate --from axios --framework vue --write
npx tanstack-fetch migrate --from ofetch --framework nuxt --write
npx tanstack-fetch migrate --from fetch --framework nextjs --write
npx tanstack-fetch migrate --from axios --framework solid --write
npx tanstack-fetch migrate --from axios --framework angular --write
npx tanstack-fetch migrate --from fetch --framework svelte --write
npx tanstack-fetch migrate --from fetch --framework sveltekit --write
npx tanstack-fetch migrate-axios --framework react --write
FlagMeaning
--fromaxios | ky | ofetch | fetch | all
--frameworkreact | vue | nuxt | nextjs | solid | angular | svelte | sveltekit
--provider / --no-providerReact only: include / skip FetchProvider (default: ask; answer defaults to no)
--dirRoot to scan (default .)
--writeApply safe transforms (+ scaffold)
--scaffoldCustom path for generic api.ts (ignored when --framework is set)
--no-scaffoldSkip creating scaffold files

--write never fully rewrites every edge case. Always review query params, interceptors, and manual res.ok / .json() findings.

Rewritten files get import { api } from '…/lib/api' (the scaffold path, relative to the file). With --no-scaffold, a file that would need api is left unchanged and reported, unless the api module already exists. New imports go after any shebang and 'use client' / 'use server' directive.


From axios ​

axiostanstack-fetch
axios.create({ baseURL })createFetch({ baseUrl })
await axios.get(url) → response.dataawait api.get(url)
axios(url) shorthandapi.get(url)
params: { page } in the config argumentquery: { page }
isAxiosError / AxiosErrorisFetchError / FetchError
axios.defaults / axios({ url, method })reported for manual wiring
ts
// before
queryFn: async ({ signal }) => {
  const response = await axios.get('/users', { signal, params: { page: 1 } })
  return response.data
}

// after
queryFn: ({ signal }) => api.get<User[]>('/users', { signal, query: { page: 1 } })

From ky ​

kytanstack-fetch
ky.create({ prefixUrl })createFetch({ baseUrl })
await ky.get(url).json()await api.get(url)
ky.get(url).json<T>()api.get<T>(url)
searchParamsquery
HTTPErrorFetchError / isFetchError
ts
// before
const data = await ky.get('users', { searchParams: { page: 1 } }).json()

// after
const data = await api.get<User[]>('/users', { query: { page: 1 } })

From ofetch / $fetch ​

ofetchtanstack-fetch
ofetch.create({ baseURL })createFetch({ baseUrl })
$fetch(url) / ofetch(url)api.get(url)
$fetch(url, { method: 'POST', body })api.post(url, { body })
queryquery (same)
ofetch FetchErrortanstack-fetch FetchError / isFetchError
ts
// before
const users = await $fetch('/users', { query: { page: 1 } })

// after
const users = await api.get<User[]>('/users', { query: { page: 1 } })

Nuxt tip: keep Nuxt’s $fetch for Nitro routes if you want; use a shared createFetch client for your app API + Query.


From raw fetch ​

fetchtanstack-fetch
fetch(url) + res.ok + res.json()api.get(url)
Manual Authorization headercreateAuthInterceptor({ getToken }) in interceptors
Manual timeout / abort{ signal } / timeoutMs
ts
// before
queryFn: async ({ signal }) => {
  const res = await fetch('/users', { signal })
  if (!res.ok) throw new Error(await res.text())
  return res.json()
}

// after
queryFn: ({ signal }) => api.get<User[]>('/users', { signal })

Raw fetch migration is report-first: the CLI flags fetch(, res.ok, and .json(); it does not rewrite whole try/catch blocks automatically.


Framework scaffolds (--framework) ​

With --write --framework <name> the CLI writes ready-to-wire files:

FrameworkFiles
reactsrc/lib/api.ts, src/queries/users.ts (+ optional src/lib/fetch-provider.tsx)
vuesrc/lib/api.ts, src/plugins/tanstack-fetch.ts, src/queries/users.ts
nuxtlib/api.ts, plugins/tanstack-fetch.ts, composables/useApi.ts, queries/users.ts
nextjssrc/lib/api.ts, src/lib/api.server.ts (cookies + ssr-forward), src/lib/fetch-provider.tsx, src/queries/users.ts
solidsrc/lib/api.ts, src/queries/users.ts (for @tanstack/solid-query)
angularsrc/app/api.ts, src/app/queries/users.ts (for @tanstack/angular-query-experimental)
sveltesrc/lib/api.ts, src/lib/queries/users.ts (for @tanstack/svelte-query)
sveltekitsrc/lib/api.ts, src/lib/api.server.ts (ssr-forward + cookies), src/lib/queries/users.ts

Solid / Angular / Svelte work with the core createFetch client plus optional adapters: tanstack-fetch/solid, /angular, /svelte (useFetch / useSse). Wire Query the same way: return data, throw FetchError, pass { signal }.

React ​

Default scaffold is without FetchProvider — import api into queryFns (and pass { client: api } to useSse).

With --write --framework react the CLI asks:

text
Use FetchProvider for React? [y/N]
  • Enter / N (default) → api.ts + queries/users.ts
  • y → also writes src/lib/fetch-provider.tsx

Skip the prompt with --no-provider (default) or --provider.

tsx
import { api } from './lib/api'
import { usersQueryOptions } from './queries/users'
import { useQuery } from '@tanstack/react-query'

const Users = () => {
  const { data } = useQuery(usersQueryOptions)
  return <pre>{JSON.stringify(data)}</pre>
}

Optional provider wrap (when you answered y / passed --provider):

tsx
import AppFetchProvider from './lib/fetch-provider'

export default () => (
  <AppFetchProvider>
    <Users />
  </AppFetchProvider>
)

Vue ​

ts
import { createApp } from 'vue'
import { installTanstackFetch } from './plugins/tanstack-fetch'
import App from './App.vue'

const app = createApp(App)
installTanstackFetch(app)
app.mount('#app')

Nuxt ​

Install the generated plugin. Prefer:

ts
import { useFetch as useFetchClient } from 'tanstack-fetch/vue'
// or composables/useApi.ts from the scaffold

Do not confuse with Nuxt core useFetch — ours only injects the shared client.

Next.js ​

  • Client: src/lib/api.ts + optional FetchProvider
  • Server Components / Route Handlers: const api = await createServerApi() from api.server.ts

Solid ​

ts
import { createQuery } from '@tanstack/solid-query'
import { usersQueryOptions } from './queries/users'

const query = createQuery(() => usersQueryOptions)

Angular ​

ts
import { injectQuery } from '@tanstack/angular-query-experimental'
import { usersQueryOptions } from './queries/users'

readonly users = injectQuery(() => usersQueryOptions)

Svelte / SvelteKit ​

ts
import { createQuery } from '@tanstack/svelte-query'
import { usersQueryOptions } from '$lib/queries/users'

const query = createQuery(() => usersQueryOptions)

SvelteKit server load: const api = createServerApi(cookies) from $lib/api.server.

Without --framework, --write still creates a generic src/lib/api.ts.

Doctor ​

bash
npx tanstack-fetch doctor --dir ./src

Reports: tanstack-fetch / legacy deps, detected frameworks, createFetch count, leftover axios/ky/ofetch imports, and queryFn call sites that may be missing signal.

Migration checklist ​

Use /guide/migrate/checklist after the CLI scan to verify signal, interceptor, and error-shape rewrites.

MIT Licensed · Created by Mohammad Garmabi · Not an official TanStack package