در نسخه 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 یک Typed Fetch Client است که API آن برای استفاده در کنار TanStack Query طراحی شده است.
قرارداد اصلی آن ساده است:
در حالت موفق، data را برمیگرداند.
در HTTP Error یک FetchError تایپشده throw میکند.
از 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 میشوند بسیار کاربردی است.
میتوانید با این Shortcut آن را باز و بسته کنید:
Alt + Shift + F
در macOS:
⌥ ⇧ F
برای هر Request اطلاعاتی مثل اینها نمایش داده میشود:
Method Path Status Duration Attempts Call Site
مثلاً:
GET /api/profile 200 143ms profile.hook.ts
یعنی علاوه بر اطلاعات Network، میتوانیم بفهمیم Request از کجای Application آمده است.
برای SSE وضعیت Stream اهمیت زیادی دارد.
در نسخه 1.4.0 وضعیت میتواند به شکل زیر باشد:
pending → live → success
یا در صورت خطا:
pending → live → error
و در صورت Cancel شدن:
pending → live → aborted
همچنین Eventهای دریافتی SSE قابل مشاهده هستند:
id name payload
در نتیجه برای Debug کردن Stream لازم نیست یک Logger جداگانه در console بنویسید.
DevTools میتواند Requestهای SSR و Edge را از Requestهای معمولی Browser تشخیص دهد.
یکی از کاربردهای مهمش بررسی Forward شدن Cookie و Authentication Context است، بدون اینکه Secretها را در DevTools نمایش دهد.
برای tRPC نیز Requestها در همان جریان DevTools ثبت میشوند.
در Adapter مربوط به tRPC از:
meta.operation = 'trpc'
برای تشخیص نوع Operation استفاده میشود.
یکی از بخشهایی که برای من در این 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 مرورگر برای بررسی اتفاقات روی 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، Response موفق tRPC میتوانست onResponse را رد کند.
در نتیجه ابزارهای Logging و DevTools همیشه نمیتوانستند Timing مربوط به Request موفق را مشاهده کنند.
در نسخه جدید، Adapter برای Response موفق onResponse را اجرا میکند و Body همچنان برای Parser خود tRPC unread باقی میماند.
Streamهای SSE رفتار متفاوتی نسبت به HTTP معمولی دارند.
قبلاً Lifecycle مشخصی برای پایان Stream وجود نداشت.
در نسخه 1.4.0، onSseClose اضافه شده است.
بنابراین وقتی Stream به شکل صحیح بسته شود:
live ↓ onSseClose ↓ success
و اگر خطا یا Abort اتفاق بیفتد، وضعیت مناسب ثبت میشود.
اگر 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 دیده میشوند.
برای DevTools یک Demo آنلاین هم آماده کردهام که بدون نصب میتوانید امتحانش کنید:
میتوانید 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
بهتر است DevTools را فقط در محیط Development فعال کنید:
if (import.meta.env.DEV) { setupDevtools(api) }
اگر در یک پروژه واقعی از DevTools استفاده کردید، خوشحال میشوم بدانم در نسخههای بعدی چه چیزی اضافه شود؛ مثلاً Filter، Export، React Wrapper یا قابلیت دیگری.