tanstack-fetch 1.5.0؛ پشتیبانی از Vue 3 و Nuxt

tanstack-fetch 1.5.0؛ پشتیبانی از Vue 3 و Nuxt

نسخه 1.5.0 از tanstack-fetch منتشر شد.

در این نسخه، پشتیبانی رسمی از Vue 3 و Nuxt اضافه شده است؛ با همان مدل ذهنیای که کاربران TanStack Query به آن عادت دارند:

1. در حالت موفق، داده را برگردان

2. در خطای HTTP، یک FetchError پرتاب کن

3. AbortSignal را به درخواست منتقل کن

هدف tanstack-fetch این است که یک HTTP client کوچک، typed و قابل استفاده در کنار TanStack Query باشد؛ بدون اینکه خودش نقش data-fetching library را بازی کند.

نکته: tanstack-fetch یک پکیج رسمی TanStack نیست. این پروژه مستقل است و با الهام از مدل ذهنی TanStack Query طراحی شده است.

در نسخه 1.5.0 چه چیزی اضافه شده؟

مهمترین تغییر این نسخه، اضافه شدن helperهای رسمی برای Vue 3 و Nuxt است.

ExportکاربردcreateFetchPluginنصب کلاینت با app.use یا استفاده در NuxtprovideFetchClientProvide کردن کلاینت در کامپوننت والدuseFetchدریافت کلاینت مشترک از injectuseSseاتصال به SSE و مدیریت وضعیت stream

یکی از نکات مهم این طراحی این است که helperهای Vue باعث نمیشوند هستهی HTTP بزرگتر و پیچیدهتر شود.

هستهی HTTP در حدود 4.81KB gzip است و قابلیتهایی مثل SSE، پلاگینها، React، Vue، tRPC و DevTools به صورت جداگانه قابل import هستند.

useFetch قرار نیست HTTP Request بزند

اگر با Nuxt کار کرده باشید، احتمالاً اسم useFetch برایتان آشناست.

اما useFetch در tanstack-fetch/vue با useFetch خود Nuxt یک تفاوت اساسی دارد.

این helper فقط کلاینتی را که قبلاً provide شده دریافت میکند:

import { useFetch as useFetchClient } from 'tanstack-fetch/vue'

بنابراین:

const api = useFetch()

به معنی ارسال یک HTTP request نیست.

در واقع api همان instance مربوط به createFetch است که از طریق Vue inject دریافت شده است.

این تفکیک باعث میشود مسئولیتها مشخص باقی بمانند:

• createFetch → مدیریت HTTP

• useFetch → دسترسی به client

• TanStack Query → مدیریت server state

• useSse → مدیریت SSE

استفاده در Vue 3

ابتدا یک client ایجاد میکنیم:

import { createFetch } from 'tanstack-fetch'
import { createFetchPlugin, useFetch } from 'tanstack-fetch/vue'

const api = createFetch({
  baseUrl: import.meta.env.VITE_API_URL,
  getToken: () => localStorage.getItem('access_token'),
})

createApp(App)
  .use(createFetchPlugin({ client: api }))
  .mount('#app')

حالا در component میتوانیم همان client را دریافت کنیم:

<script setup lang="ts">
const api = useFetch()

const users = await api.get<User[]>('/users')

در این مدل، component مجبور نیست خودش client را بسازد یا configuration مربوط به authentication و base URL را بداند.

SSE در Vue

در نسخه 1.5.0، استفاده از SSE نیز با helper مخصوص Vue سادهتر شده است.

مثلاً:

<script setup lang="ts">
import { createFetch } from 'tanstack-fetch/sse'
import { useSse } from 'tanstack-fetch/vue'

const api = createFetch({
  plugins: ['sse-resume'],
})

const { data, status, close } = useSse('/orders/stream', {
  client: api,
})

و وضعیت stream از طریق status در دسترس است:

'connecting'
| 'connected'
| 'disconnected'
| 'error'

این یعنی component میتواند بدون پیادهسازی مستقیم lifecycle مربوط به EventSource، وضعیت connection را مدیریت کند.

استفاده در Nuxt

برای Nuxt میتوانیم client را به عنوان یک plugin به application اضافه کنیم.

برای مثال:

// plugins/tanstack-fetch.ts

import { createFetch } from 'tanstack-fetch/sse'
import { createFetchPlugin } from 'tanstack-fetch/vue'

export default defineNuxtPlugin((nuxtApp) => {
  const api = createFetch({
    baseUrl: useRuntimeConfig().public.apiBase,
    plugins: ['sse-resume'],
  })

  nuxtApp.vueApp.use(
    createFetchPlugin({
      client: api,
    }),
  )
})

بعد از آن، componentهای Vue/Nuxt میتوانند از همان client مشترک استفاده کنند.

چرا این معماری؟

یکی از اهداف اصلی tanstack-fetch این است که HTTP client و server-state management را از هم جدا نگه دارد.

برای مثال، tanstack-fetch مسئول مواردی مثل:

• HTTP request

• authentication

• typed response

• FetchError

• AbortSignal

• interceptor/plugin

• SSE

است.

در مقابل، ابزارهایی مثل TanStack Query میتوانند مسئول:

• caching

• retries

• invalidation

• stale state

• mutations

• synchronization

باشند.

در نتیجه میتوان چیزی شبیه این داشت:

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

HTTP client فقط request را انجام میدهد و Query مسئول lifecycle مربوط به server state باقی میماند.

یک HTTP Client کوچک، نه یک Framework جدید

یکی از تصمیمهای مهم در tanstack-fetch این است که قابلیتهای مختلف تا حد ممکن جدا نگه داشته شوند.

برای مثال:

import { createFetch } from 'tanstack-fetch'

برای استفاده معمولی کافی است.

اگر SSE لازم داشته باشید:

import { createFetch } from 'tanstack-fetch/sse'

و برای DevTools یا integrationهای دیگر نیز entry pointهای جداگانه وجود دارند.

این رویکرد باعث میشود application مجبور نباشد قابلیتهایی را که استفاده نمیکند، به bundle اصلی خود اضافه کند.

از FetchError تا AbortSignal

مدل خطا نیز بخش مهمی از طراحی tanstack-fetch است.

در صورت دریافت HTTP error، به جای اینکه application مجبور باشد هر بار response را بررسی کند، client یک FetchError پرتاب میکند.

از طرف دیگر، AbortSignal مستقیماً به request منتقل میشود؛ بنابراین میتوان آن را با lifecycle ابزارهایی مثل TanStack Query هماهنگ کرد.

این همان جایی است که مدل ذهنی tanstack-fetch و TanStack Query به خوبی کنار یکدیگر قرار میگیرند.

نصب

برای نصب آخرین نسخه:

npm install tanstack-fetch

یا:

pnpm add tanstack-fetch

لینکها

راهنمای Vue و Nuxt

https://mohamadgarmabi.github.io/tanstack-fetch/guide/vue

پست رسمی انتشار نسخه 1.5.0

https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-1-5

npm

https://www.npmjs.com/package/tanstack-fetch

GitHub

https://github.com/mohamadgarmabi/tanstack-fetch

جمعبندی

نسخه 1.5.0 یک قدم مهم برای گسترش tanstack-fetch به خارج از اکوسیستم React است.

با اضافه شدن integrationهای Vue 3 و Nuxt، حالا میتوان همان client را با یک الگوی مشابه در پروژههای Vue استفاده کرد؛ در حالی که هستهی HTTP همچنان کوچک و مستقل باقی میماند.

اگر در پروژه Vue یا Nuxt خودتان به یک HTTP client typed و سبک نیاز دارید که بتواند در کنار TanStack Query کار کند، میتوانید tanstack-fetch را بررسی کنید.

tanstack-fetch یک پروژه مستقل و غیررسمی نسبت به TanStack است.