ورژن 3 SvelteKit منتشر شد؛ کانفیگ میره توی Vite و alias معروف lib عوض میشه

تیم Svelte روز ۱ اکتبر ۲۰۲۶ نسخه‌ی پایدار SvelteKit 3 رو منتشر کرد، حدود هفت هفته بعد از release candidate که ۱۳ آگوست اومده بود. این یه major release واقعیه و چند تا breaking change داره که تقریباً هر پروژه‌ی SvelteKit رو درگیر می‌کنه؛ خبر خوب اینه که یه ابزار migration رسمی هم همراهشه.

چه چیزهایی عوض شده؟

بزرگ‌ترین تغییر، جابه‌جایی کانفیگ پروژه‌ست: تنظیمات SvelteKit دیگه توی فایل svelte.config.js نیست و باید توی فایل vite.config.ts قرار بگیره. تغییر دوم که حتماً توی کدت حسش می‌کنی، جایگزین شدن alias معروف lib با subpath import های استاندارد Node.js هست، یعنی importها از پیشوند دلار به پیشوند هشتگ تغییر می‌کنن. alias های دیگه مثل app و env همچنان با پیشوند دلار می‌مونن، پس یه مدت با یه قرارداد ترکیبی کار می‌کنی:

// قبل از SvelteKit 3
import { formatDate } from '$lib/utils';

// SvelteKit 3
import { formatDate } from '#lib/utils';

علاوه بر این، فایل tsconfig پروژه حالا باید از یه مسیر جدید در app/tsconfig ارث‌بری کنه، به‌جای فایل تولیدشده توی پوشه‌ی svelte-kit. پیاده‌سازی service worker ها هم ساده‌تر شده و تنظیماتشون رو از ماژول‌های app میگیرن.

قابلیت‌های تازه

متغیرهای محیطی حالا یه قابلیت پایدار و درجه‌یک هستن (قبلاً experimental بودن). توی نسخه‌ی جدید، متغیرها رو توی یه فایل مشخص با کتابخونه‌های سازگار با Standard Schema مثل Zod، Valibot یا ArkType تعریف می‌کنی و اعتبارسنجی موقع استارت اپ انجام میشه، یعنی خطای کانفیگ همون اول معلوم میشه، نه وسط اجرا.

مدیریت خطا هم یکپارچه‌تر شده: کامپوننت error هم خطاهای load و هم خطاهای render رو مدیریت می‌کنه، همه‌ی خطاها از طریق handleError عبور می‌کنن، و stack trace ها حالا sourcemap دارن که دیباگ production رو راحت‌تر می‌کنه. shallow routing هم به‌جای API قبلی، با goto و گزینه‌ی shallow انجام میشه.

مهاجرت از نسخه‌ی قبلی

تیم Svelte یه دستور migration رسمی داده که تغییرات مکانیکی رو خودکار انجام میده و برای بقیه یه لیست TODO تولید می‌کنه:

npx sv migrate sveltekit-3 --tasks all --confirm

توصیه‌ی منطقی اینه که این دستور رو روی یه branch تمیز اجرا کنی و diff رو قبل از merge مرور کنی. برای پروژه‌ی جدید هم دستور استاندارد همونه که همیشه بود:

npx sv create my-new-app

چیزی که هنوز نیومده

Remote functions، همون قابلیت RPC تایپ‌سیف بین کلاینت و سرور که خیلی‌ها منتظرش بودن، توی این نسخه هم پایدار نشده. تیم Svelte میگه این قابلیت اولویت اصلیه، ولی چون به Async Svelte وابسته‌ست که فعلاً پشت یه فلگ experimental قرار داره، هنوز باید با فعال کردن اون فلگ ازش استفاده کنی.

یه نکته‌ی احتیاطی درباره‌ی نیازمندی‌ها: توی پست release candidate گفته شده بود SvelteKit 3 به Svelte 5 و Vite 8 نیاز داره، ولی پست انتشار نهایی نسخه‌های حداقل Node، Svelte و Vite رو دوباره ذکر نکرده. قبل از آپدیت، این نیازمندی‌ها رو توی مستندات رسمی هم چک کن.