مهاجرت از Axios، Ky، Ofetch یا Fetch به tanstack-fetch با یک دستور

یک کلاینت HTTP مناسب TanStack Query، به‌همراه CLI برای پیدا کردن call siteها و اسکفولد React، Vue، Nuxt و Next.js

اگر از TanStack Query استفاده می‌کنید، queryFn عملاً از شما سه چیز می‌خواهد:

1. دیتا برگرداند، نه Response خام

2. روی خطا throw کند تا isError و error handling درست کار کنند

3. AbortSignal را رعایت کند تا cancellation درخواست‌ها درست انجام شود

بیشتر HTTP Clientها دقیقاً برای این مدل طراحی نشده‌اند. معمولاً باید res.data را باز کنید، روی Response متد .json() را صدا بزنید یا حواستان باشد signal را به درخواست منتقل کنید.

tanstack-fetch برای همین مدل ذهنی ساخته شده است: یک HTTP client تایپ‌شده که با الگوی استفاده از TanStack Query هماهنگ است.

در نسخه 1.6.2 یک CLI برای migration اضافه شده که می‌تواند axios، ky، ofetch و fetch را اسکن کند، الگوهای امن را rewrite کند و برای React، Vue، Nuxt و Next.js فایل‌های اولیه را scaffold کند.

نکته: tanstack-fetch یک پروژه رسمی TanStack نیست و هیچ وابستگی رسمی به تیم TanStack ندارد؛ فقط API و mental model آن با هدف هماهنگی با اکوسیستم TanStack طراحی شده است.

مستندات:
راهنمای Migration · بلاگ · npm

قبل

queryFn: async ({ signal }) => {
  const res = await axios.get('/users', {
    signal,
    params: { page: 1 }
  })

  return res.data
}

بعد

import { createFetch } from 'tanstack-fetch'

const api = createFetch({
  baseUrl: 'https://api.example.com'
})

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

یک کلاینت، دیتای مستقیم، FetchError تایپ‌شده و پشتیبانی از AbortSignal از ابتدا.

CLI Migration

ابتدا پکیج را نصب کنید:

npm install tanstack-fetch

بعد می‌توانید migration را به‌صورت dry run اجرا کنید:

npx tanstack-fetch migrate --from axios --dir ./src

npx tanstack-fetch migrate --from all --dir ./src

یا migration و scaffold را هم‌زمان انجام دهید:

npx tanstack-fetch migrate \
  --from axios \
  --framework react \
  --dir ./src \
  --write

npx tanstack-fetch migrate \
  --from ofetch \
  --framework nuxt \
  --write

npx tanstack-fetch migrate \
  --from fetch \
  --framework nextjs \
  --write

فلگ‌ها

فلگمعنی--fromaxios | ky | ofetch | fetch | all--frameworkreact | vue | nuxt | nextjs--provider / --no-providerفقط React؛ با یا بدون FetchProvider--writerewrite امن + scaffold

--write عمداً محافظه‌کار است.

الگوهای شناخته‌شده و امن rewrite می‌شوند؛ اما مواردی مثل پارامترهای پیچیده query، interceptorها یا منطق res.ok ممکن است فقط گزارش شوند تا خودتان آن‌ها را بررسی و اصلاح کنید.

بنابراین بعد از migration حتماً گزارش CLI را مرور کنید.

نگاشت سریع API

ازبهaxios.create({ baseURL })createFetch({ baseUrl })res.dataخود api.get دیتا را برمی‌گرداند.json()خود api.get دیتا را برمی‌گرداندparams در AxiosquerysearchParams در KyqueryisAxiosErrorisFetchError

در مورد fetch خام، migration بیشتر گزارش‌محور است.

CLI محل‌هایی مثل:

fetch(...)

و:

res.ok

را پیدا می‌کند و گزارش می‌دهد تا بتوانید آن بخش را متناسب با منطق پروژه خودتان بازنویسی کنید.

اسکفولد برای فریم‌ورک‌های مختلف

CLI می‌تواند بر اساس فریم‌ورک شما ساختار اولیه را هم ایجاد کند:

فریم‌ورکخروجیReactapi.ts + queries/users.ts + Provider اختیاریVueapi.ts + pluginNuxtapi + plugin + useApiNext.jsclient + api.server.ts با cookie و ssr-forward

React و FetchProvider

در React، اگر migration را با --write اجرا کنید، CLI می‌تواند درباره استفاده از FetchProvider از شما سؤال کند:

Use FetchProvider for React? [y/N]

پیش‌فرض N است؛ یعنی بدون Provider.

در این حالت می‌توانید client را مستقیماً به queryها پاس بدهید:

client: api

اگر نمی‌خواهید CLI سؤال بپرسد، می‌توانید صریحاً یکی از این دو فلگ را استفاده کنید:

--provider

یا:

--no-provider

چرا tanstack-fetch؟

هدف اصلی این پروژه ساده است: HTTP layer باید با مدل استفاده از TanStack Query هماهنگ باشد.

چند قابلیت مهم:

• مناسب برای استفاده مستقیم در queryFn و mutationFn

• خطاهای تایپ‌شده با اطلاعاتی مثل status و body

• handlerهای قابل تنظیم برای status codeهای مختلف، از جمله 401 تا 429

• refresh token و جلوگیری از refreshهای هم‌زمان

• پشتیبانی از SSR و forwarding کوکی

• SSE با Authorization و قابلیت resume

• پشتیبانی از AbortSignal

• هسته HTTP حدود 4.8KB gzip

اگر می‌خواهید تفاوت آن با Axios، Ky، Ofetch و Fetch را دقیق‌تر ببینید:

مقایسه کامل HTTP Clientها

امتحان کنید

اگر می‌خواهید ابتدا ببینید پروژه شما چه چیزهایی برای migration دارد، بدون تغییر فایل‌ها شروع کنید:

npx tanstack-fetch migrate \
  --from all \
  --dir ./src

و اگر آماده rewrite و scaffold هستید:

npx tanstack-fetch migrate \
  --from all \
  --framework react \
  --write \
  --no-provider

لینک‌ها

• سایت tanstack-fetch

• بلاگ نسخه 1.6.2

• راهنمای Migration

• GitHub

• npm

اگر روی یک پروژه واقعی این CLI را اجرا کردید، خوشحال می‌شوم بدانم چه migrationهایی را درست تشخیص داد، چه چیزهایی را از دست داد و کجا نیاز به اصلاح دستی داشت.

همین بازخوردها می‌توانند مشخص کنند که transformerهای نسخه‌های بعدی باید روی چه الگوهایی تمرکز کنند.