‏راهنمای مهاجرت به SvelteKit 3: چی عوض شده؟

تیم Svelte راهنمای مهاجرت به SvelteKit 3 رو منتشر کرده. مهم‌ترین تغییر اینه که فایل svelte.config.js دیگه پشتیبانی نمی‌شه و همه تنظیمات باید به پلاگین sveltekit توی vite.config.js داده بشه. گزینه‌هایی که قبلاً زیر config.kit بودن حالا مستقیم گزینه‌های خود پلاگین هستن. برای خیلی از تغییرها می‌شه از دستور npx sv migrate sveltekit-3 استفاده کرد. توصیه تیم اینه که اول به آخرین نسخه 2.x برید تا هشدارهای deprecation (یعنی اخطار درباره چیزهایی که قراره حذف بشن) رو ببینید.

حداقل نسخه‌ها هم بالا رفته: Node 22.17، TypeScript 6، Svelte 5.57.1، Vite 8.0.12 (اولین نسخه Vite 8 که rolldown پایدار رو داره) و @sveltejs/vite-plugin-svelte نسخه 7. چندتا گزینه هم حذف شدن، مثلاً preloadStrategy چون modulepreload حالا همه‌جا پشتیبانی می‌شه، و csrf.checkOrigin که جاشو به csrf.trustedOrigins داده. یعنی دیگه نمی‌شه محافظت CSRF رو خاموش کرد و فقط می‌شه originهای مطمئن رو اجازه داد.

alias معروف $lib دیگه خودکار ساخته نمی‌شه. جاش باید #lib رو توی فیلد imports فایل package.json تعریف کنید که روی subpath imports خود Node (یعنی aliasهایی که Node و Vite و TypeScript خودشون می‌فهمن) سواره:

{
	"imports": {
		"#lib": "./src/lib/index.js",
		"#lib/*": "./src/lib/*"
	}
}

بعد باید همه $libها رو با #lib عوض کنید و پسوند فایل (.js یا .ts) رو هم به importها اضافه کنید.

تو بخش ناوبری هم تغییرهای زیادی هست. pushState و replaceState برای shallow routing (یعنی عوض کردن URL بدون لود کامل صفحه) deprecated شدن و جاشون goto با گزینه shallow: true اومده. invalidateAll هم جاشو به refreshAll داده که page.state رو پاک نمی‌کنه. goto حالا برای URLی که به هیچ route داخلی نمی‌رسه خطا می‌ده و preloadData هم در صورت شکست، نتیجه‌ای از نوع error برمی‌گردونه که باید براش یه شاخه جدا بنویسید.

چندتا ماژول هم کلاً حذف شدن. $app/stores حذف شده و باید از $app/state استفاده کنید (یعنی page به جای $page). ماژول $service-worker هم رفته و جاش $app/env، $app/manifest و $app/paths اومدن. $app/environment اسمش شده $app/env و خروجی‌های base و assets و resolveRoute هم از $app/paths حذف شدن و باید از asset و resolve استفاده کرد. page.url هم حالا فقط خوندنیه، پس اگه بخواید تغییرش بدید اول باید یه کپی ازش بسازید.

یه تغییر رفتاری مهم دیگه اینه که updated.current حالا خودکار آپدیت می‌شه. یعنی SvelteKit موقع ناوبری، صدا زدن remote functionها، برگشتن به تب و هر یک ساعت یه بار چک می‌کنه نسخه جدیدی دیپلوی شده یا نه. helperهای json و text هم deprecated شدن و باید از Response.json و new Response استفاده کنید.

نکات کلیدی:

• فایل svelte.config.js حذف شده و تنظیمات می‌ره توی پلاگین sveltekit در vite.config.js
• حداقل نسخه‌ها: Node 22.17، TypeScript 6، Svelte 5.57.1، Vite 8.0.12
• alias $lib جاشو به #lib در فیلد imports فایل package.json داده
• ماژول‌های $app/stores و $service-worker حذف شدن
• invalidateAll و pushState جاشونو به refreshAll و goto با shallow: true دادن
• دستور npx sv migrate sveltekit-3 خیلی از تغییرها رو خودکار انجام می‌ده