ویرگول
ورودثبت نام
garmabi.mohammad73
garmabi.mohammad73Senior Software Engineer با تمرکز بر Frontend، React و TypeScript. علاقه‌مند به Software Architecture، System Design، Open Source و ساخت ابزارهای ساده و مقیاس‌پذیر.
garmabi.mohammad73
garmabi.mohammad73
خواندن ۴ دقیقه·۲ ماه پیش

See Every Fetch؛ دیباگ HTTP، SSE، SSR و tRPC با tanstack-fetch

See Every Fetch؛ دیباگ HTTP، SSE، SSR و tRPC با tanstack-fetch

در نسخه 1.4.0 پکیج tanstack-fetch یک DevTools جدید اضافه شده که هدفش خیلی ساده است:

به‌جای اینکه فقط ببینیم یک Request چه اتفاقی برایش افتاده، بفهمیم چه بخشی از کد ما آن را ایجاد کرده است.

وقتی یک درخواست در Network Tab خراب می‌شود، معمولاً این اطلاعات را داریم:

GET /api/profile 500

اما سؤال‌های مهم‌تر معمولاً این‌ها هستند:

  • کدام Hook یا Component این درخواست را ایجاد کرده؟

  • درخواست از SSR آمده یا Browser؟

  • آیا Request دوباره Retry شده؟

  • آیا SSE هنوز باز است یا واقعاً تمام شده؟

  • آیا tRPC از مسیر Interceptorهای ما عبور کرده؟

  • دقیقاً کدام فایل باعث این درخواست شده است؟

برای همین در نسخه 1.4.0، tanstack-fetch/devtools اضافه شده است.

tanstack-fetch چیست؟

tanstack-fetch یک Typed Fetch Client است که API آن برای استفاده در کنار TanStack Query طراحی شده است.

قرارداد اصلی آن ساده است:

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

  2. در HTTP Error یک FetchError تایپ‌شده throw می‌کند.

  3. از AbortSignal پشتیبانی می‌کند.

در کنار هسته اصلی، ماژول‌های جداگانه‌ای برای مواردی مثل این‌ها دارد:

  • SSR

  • SSE

  • Upload

  • React

  • tRPC

  • DevTools

این پروژه پکیج رسمی TanStack نیست؛ فقط API آن طوری طراحی شده که در کنار TanStack Query طبیعی باشد.

نصب

npm i [email protected]

سپس:

import { createFetch } from 'tanstack-fetch' import { setupDevtools } from 'tanstack-fetch/devtools' const api = createFetch({ baseUrl: import.meta.env.VITE_API_URL, plugins: ['trace'], }) if (import.meta.env.DEV) { setupDevtools(api) }

همین.

DevTools یک Interceptor ثبت می‌کند و یک Dock در پایین صفحه قرار می‌دهد.

پیشنهاد می‌کنم trace را هم فعال کنید تا هر Request یک شناسه پایدار داشته باشد:

requestId:attempt

این موضوع برای Requestهایی که Retry می‌شوند بسیار کاربردی است.

باز کردن DevTools

می‌توانید با این Shortcut آن را باز و بسته کنید:

Alt + Shift + F

در macOS:

⌥ ⇧ F

چه چیزهایی را می‌توان دید؟

HTTP

برای هر Request اطلاعاتی مثل این‌ها نمایش داده می‌شود:

Method Path Status Duration Attempts Call Site

مثلاً:

GET /api/profile 200 143ms profile.hook.ts

یعنی علاوه بر اطلاعات Network، می‌توانیم بفهمیم Request از کجای Application آمده است.

SSE

برای SSE وضعیت Stream اهمیت زیادی دارد.

در نسخه 1.4.0 وضعیت می‌تواند به شکل زیر باشد:

pending → live → success

یا در صورت خطا:

pending → live → error

و در صورت Cancel شدن:

pending → live → aborted

همچنین Eventهای دریافتی SSE قابل مشاهده هستند:

id name payload

در نتیجه برای Debug کردن Stream لازم نیست یک Logger جداگانه در console بنویسید.

SSR

DevTools می‌تواند Requestهای SSR و Edge را از Requestهای معمولی Browser تشخیص دهد.

یکی از کاربردهای مهمش بررسی Forward شدن Cookie و Authentication Context است، بدون اینکه Secretها را در DevTools نمایش دهد.

tRPC

برای tRPC نیز Requestها در همان جریان DevTools ثبت می‌شوند.

در Adapter مربوط به tRPC از:

meta.operation = 'trpc'

برای تشخیص نوع Operation استفاده می‌شود.

Call Graph؛ قسمت مهم ماجرا

یکی از بخش‌هایی که برای من در این DevTools مهم بود، پیدا کردن Source Request است.

فرض کنید فقط این را می‌بینیم:

GET /api/profile 500

DevTools می‌تواند مسیر Application را هم نشان دهد:

ProfilePage ↓ useProfile ↓ profile.hook.ts ↓ api.get()

بعد می‌توان روی Node مربوط به Source کلیک کرد و فایل را مستقیماً در:

  • Cursor

  • Zed

  • VS Code

باز کرد.

یعنی مسیر Debug می‌شود:

Failed Request ↓ DevTools ↓ Call Graph ↓ Source File ↓ Editor

این چیزی است که Network Tab به‌تنهایی نمی‌تواند به شما بدهد.

چرا فقط Network Tab کافی نیست؟

Network Tab مرورگر برای بررسی اتفاقات روی Wire عالی است.

اما این DevTools به Pipeline خود createFetch متصل است.

نوعتشخیصHTTPFetch معمولیSSRsource: 'ssr' | 'edge' یا Incoming AuthSSEonSseOpen / Events / onSseClosetRPCmeta.operation = 'trpc'

در نتیجه یک Dock می‌تواند Requestهایی را که از مسیرهای مختلف آمده‌اند کنار هم نشان دهد:

React Query ↓ createFetch ↓ Interceptor Pipeline ↓ HTTP / SSE / SSR / tRPC ↓ DevTools

دو تغییر مهم در نسخه 1.4.0

مشکل tRPC

قبل از نسخه 1.4.0، Response موفق tRPC می‌توانست onResponse را رد کند.

در نتیجه ابزارهای Logging و DevTools همیشه نمی‌توانستند Timing مربوط به Request موفق را مشاهده کنند.

در نسخه جدید، Adapter برای Response موفق onResponse را اجرا می‌کند و Body همچنان برای Parser خود tRPC unread باقی می‌ماند.

مشکل SSE Pending

Streamهای SSE رفتار متفاوتی نسبت به HTTP معمولی دارند.

قبلاً Lifecycle مشخصی برای پایان Stream وجود نداشت.

در نسخه 1.4.0، onSseClose اضافه شده است.

بنابراین وقتی Stream به شکل صحیح بسته شود:

live ↓ onSseClose ↓ success

و اگر خطا یا Abort اتفاق بیفتد، وضعیت مناسب ثبت می‌شود.

استفاده از یک Store برای چند Client

اگر HTTP و SSE را با Factoryهای جدا ساخته باشید، باز هم می‌توانید یک Store مشترک داشته باشید:

import { createFetch } from 'tanstack-fetch/sse' import { createDevtools, mountDevtools, } from 'tanstack-fetch/devtools' const dt = createDevtools({ http: true, sse: true, ssr: true, trpc: true, }) const api = createFetch({ plugins: ['trace', 'sse-resume'], interceptors: [dt.interceptor], }) mountDevtools({ store: dt.store, open: true, })

در این حالت همه Requestها در یک Dock دیده می‌شوند.

نسخه Live را امتحان کنید

برای DevTools یک Demo آنلاین هم آماده کرده‌ام که بدون نصب می‌توانید امتحانش کنید:

DevTools Example

می‌توانید HTTP، Upload، SSR، SSE و tRPC را اجرا کنید و بعد با:

Alt + Shift + F

DevTools را باز کنید.

چه زمانی کاربردی است؟

این ابزار بیشتر برای Development و Debugging طراحی شده است.

مثلاً:

TanStack Query

برای پیدا کردن Requestهای تکراری، Retryها و Raceهای احتمالی.

SSR Authentication

برای بررسی اینکه Cookie و Authentication Context درست Forward شده‌اند.

SSE

برای دیدن Eventهای Stream و Lifecycle آن.

Debug کردن Source

به‌جای اینکه فقط بدانیم:

500 POST /api/orders

بتوانیم مستقیم به چیزی مثل این برسیم:

createOrder.hook.ts:42

در Production فعالش نکنید

بهتر است DevTools را فقط در محیط Development فعال کنید:

if (import.meta.env.DEV) { setupDevtools(api) }

لینک‌ها

  • npm — tanstack-fetch

  • Documentation

  • Changelog 1.4.0

  • Live DevTools Demo

  • GitHub

اگر در یک پروژه واقعی از DevTools استفاده کردید، خوشحال می‌شوم بدانم در نسخه‌های بعدی چه چیزی اضافه شود؛ مثلاً Filter، Export، React Wrapper یا قابلیت دیگری.

apireactnextjs
۱
۰
garmabi.mohammad73
garmabi.mohammad73
Senior Software Engineer با تمرکز بر Frontend، React و TypeScript. علاقه‌مند به Software Architecture، System Design، Open Source و ساخت ابزارهای ساده و مقیاس‌پذیر.
شاید از این پست‌ها خوشتان بیاید