رفتن به محتوا
triplem.dev
بلاگnuxt

Nuxt 4.6.1: پچ بعدی برای هندلرهای dev server، تایپ‌های $fetch و Vite 8.1+

۵ دقیقه مطالعه
nuxt
nitro
typescript

Nuxt 4.6 سطح بزرگی را عرضه کرد: nuxt/server، سشن‌ها، $fetch تایپ‌دار بازنویسی‌شده و CLI v4. چند روز بعد، نسخه v4.6.1 (با تاریخ ۹ اکتبر) ۲۵ اصلاح می‌آورد. این یک پچ است، اما محتوایش مثل نقشه‌ای است از جاهایی که تغییرات 4.6 با پروژه‌های واقعی اصطکاک پیدا کرد. اگر پس از ارتقا به 4.6 رفتار عجیبی در dev server یا خطای تایپ دیدید، این نسخه را بخوانید.

صفحه‌ی release فقط فهرست اصلاحات است و توضیح ندارد. هرجا معنای یک اصلاح را تفسیر می‌کنم، صریح می‌گویم.

هندلرهای dev server

این بزرگ‌ترین دسته است. خط 4.6 هندلر dev server را قابل‌حمل کرد و این پچ درزهای آن را می‌بندد:

  • هر هندلر dev server حالا فقط یک بار ثبت می‌شود. عبارت‌بندی نشان می‌دهد ثبت تکراری ممکن بوده؛ issue مرتبطی با شرح علائم پیدا نکردم و حدس نمی‌زنم.
  • مسیر هندلرهای dev روی هر دو نسخه‌ی major از Nitro تطبیق داده می‌شود. این با هدف 4.6 یعنی کار روی Nitro v2 و v3 جور است.
  • هندلرهای dev server در Nuxt حالا یک RequestEvent دریافت می‌کنند، هماهنگ با event قابل‌حمل که با nuxt/server آمد.
  • پلاگین‌های deploy target در dev کار می‌کنند و گزارش خطای dev شامل request است.
  • رندر صفحه‌ی خطا مسیر را دریافت می‌کند.
  • اگر BroadcastChannel خطا بدهد، پخش خطای dev غیرفعال می‌شود؛ اصلاحی که همراه Vite انجام شده.

اگر ماژول یا middlewareِ فقط-dev را بر اساس شکل هندلر 4.6.0 نوشته‌اید، روی 4.6.1 دوباره تست کنید. توصیه‌ی عملی: در dev به ترتیب یا تعداد ثبت هندلرها تکیه نکنید، چون دقیقاً همین ناحیه اصلاح شده است.

تایپ‌ها: $fetch، nodenext و exportها

$fetch بازنویسی‌شده تیتر اصلی 4.6 بود، پس عجیب نیست که چند اصلاح به تایپ‌ها مربوط باشد:

  • $fetch سراسری با TypedFetch خودِ Nuxt تایپ می‌شود.
  • وقتی نوع پاسخ نام‌گذاری شده باشد، هر baseURL پذیرفته می‌شود. برداشت من این است که ترکیب نوع پاسخ نام‌دار با base URL سفارشی قبلاً رد می‌شد.
  • تایپ‌های شیء Serialize با JSON هم‌راستا شدند.
  • تایپ‌های در دسترس از composableهای async data اکسپورت می‌شوند؛ اگر دور useAsyncData یا useFetch wrapper می‌نویسید و باید نوع بازگشتی را نام ببرید، این مهم است.
  • false در تایپ‌های setPageLayout مجاز است.
  • declarationهای nitropack/types زیر nodenext resolve می‌شوند.

مورد آخر اگر پکیج یا لایه‌ای را به resolution از نوع nodenext برده‌اید توجه می‌خواهد:

jsonc
// tsconfig.json of a shared package or layer
{
    "compilerOptions": {
        "module": "nodenext",
        "moduleResolution": "nodenext"
    }
}

با این تنظیم، resolve زیرمسیرها نسبت به exports پکیج سخت‌گیر است، پس declarationای که با bundler resolve می‌شد ممکن است شکست بخورد. اگر با alias در paths به nitropack/types دور زده بودید، بعد از ارتقا alias را حذف کنید و nuxt typecheck بزنید.

wrapper تایپ‌دار نمونه‌ی کدی است که از تایپ‌های اکسپورت‌شده‌ی async data سود می‌برد:

ts
// composables/useApi.ts
export function useApi<T>(url: string) {
    // The wrapper keeps Nuxt's key, dedupe and caching behaviour intact
    return useFetch<T>(url, { key: `api:${url}` });
}

صفحه‌ی release نام تایپ‌های تازه‌دسترس را نمی‌دهد؛ پیشنهادهای ادیتور را ببینید و به نام‌های حفظی تکیه نکنید.

اصلاحات سمت Vite

سه اصلاح در یکپارچه‌سازی Vite هست:

  • راهنمای deps حالا با پیام‌های optimizer در Vite 8.1+ مطابقت دارد. اگر Vite جدیدتر از baseline نسخه‌ی Nuxt اجرا می‌کنید، احتمالاً این راهنما شناسایی نمی‌شد.
  • اسکن وابستگی‌ها دیگر روی importهای مجازی داخل پکیج‌های نصب‌شده متوقف نمی‌شود.
  • URLهای استایل inline جداکننده‌ی رشته‌ی دربرگیرنده را تشخیص می‌دهند، پس url() داخل استایل داخل کوتیشن درست parse می‌شود.

جدا از این، باندل سرور حالا unhead را از Nuxt resolve می‌کند و وقتی runtime خود Nuxt به مسیرهای ویندوزی resolve شود، inline می‌شود. کاربران ویندوز که resolve عجیب باندل سرور دیده‌اند ابتدا اینجا را نگاه کنند.

Runtime، هیدراسیون و موارد جانبی

یک اصلاح runtime ارزش دوبار خواندن دارد: onServerPrefetch برای هیدراسیون useId حفظ می‌شود. useId شناسه‌هایی می‌سازد که باید بین سرور و کلاینت یکی باشند؛ از دست رفتن hook سمت سرور می‌توانست به mismatch هیدراسیون برسد. یادداشت‌ها موردی را شرح نمی‌دهند، پس این استنباط من است: اگر بعد از 4.6 هشدار mismatch شناسه دیدید، دوباره تست کنید.

موارد کوچک‌تر:

  • Kit پکیجی را که زیرمسیر گمشده به آن تعلق دارد نصب می‌کند، که مسیر شکست را وقتی import resolve نمی‌شود بهتر می‌کند.
  • regexp نسخه‌ی nightly با قالب نسخه‌ی nightly هم‌راستا شد.
  • پکیج Schema پوشه‌ی .wrangler را نادیده می‌گیرد، که برای پروژه‌های Cloudflare مفید است.
  • پسوند export مربوط به publishConfig به‌روز شد.

آیا ارتقا بدهیم؟

نظر من، با تکیه بر یادداشت‌های release و نه بنچمارک:

  1. اگر روی 4.5.x هستید و هنوز به 4.6 نرفته‌اید، مستقیم به 4.6.1 بروید.
  2. اگر روی 4.6.0 هستید و از هندلرهای سفارشی dev server، ماژول‌هایی که به dev server وصل می‌شوند، یا لایه‌های nodenext استفاده می‌کنید، ارتقا بدهید و دوباره تست کنید. اصلاحات همین‌جا متمرکزند.
  3. اگر هیچ‌کدام را ندارید، پچ یک نگهداری کم‌ریسک است.
bash
npx nuxt upgrade --dedupe

سپس type check و build پروداکشن بزنید، چون چند اصلاح روی resolve تایپ‌ها و باندل سرور اثر می‌گذارد نه رفتار مرورگر.

بده‌بستان‌ها و نکات احتیاط

پچ سریع بعد از یک minor چیزی به شما می‌گوید. minor نسخه‌ی 4.6 سطح سرور و سیستم تایپ را هم‌زمان عوض کرد و پروژه‌های با ساختار غیرمعمول (لایه‌های nodenext، مسیرهای ویندوزی، Vite جدیدتر) زود شکاف‌ها را پیدا کردند. این عادی است و عادتی را تقویت می‌کند: minorها را در CI پین کنید، بگذارید یک branch اولین پچ را بگیرد و بعد از موفقیت typecheck ارتقا دهید.

همچنین نشان می‌دهد رفتار Nuxt چقدر به نسخه‌ی Vite و Nitro زیرش وابسته است. اصلاحاتی که به پیام‌های Vite 8.1+ و هر دو major نسخه‌ی Nitro اشاره می‌کنند یعنی رفتار واقعی شما ترکیبی سه‌گانه است. نسخه‌ی Nuxt، Vite و Nitro را در گزارش باگ بنویسید، چون همین پچ Nuxt می‌تواند روی ترکیب‌های مختلف متفاوت رفتار کند.

منابع