SvelteKit 3 Çıktı: Ayarlar vite.config.ts'ye Taşındı, $lib Yerine #lib, Kaldırılan API'ler ve Geçiş Rehberi

SvelteKit 3'te neler değişti? (What's new)

Svelte ekibinin duyurusuna göre SvelteKit 3'ün ana başlıkları şunlar: yapılandırmanın Vite dosyasına taşınması, $lib yerine #lib, daha güçlü ortam değişkenleri, daha az şablon kod isteyen service worker'lar, baştan sona iyileştirilen hata yönetimi ve daha sıkı tip güvenliği. Aynı gün komut satırı aracı sv 1.0 da çıktı; yeni projeler doğrudan SvelteKit 3 ve #lib ile oluşturuluyor, topluluk eklentisi (community add-on) API'si resmîleşti.

Çok beklenen remote functions (istemci ile sunucu arasında tip güvenli çağrı) henüz kararlı değil. Ekip bunu "en öncelikli iş" olarak tanımlıyor; kullanmak için experimental.remoteFunctions ve deneysel async Svelte bayrağı gerekiyor.

Asgari sürümler (Minimum versions)

Node 20 kullanan sunucularda geçişten önce Node'u yükseltmek gerekiyor. Node.js 26 LTS 28 Ekim'de uzun süreli destek dalına geçiyor; yeni kurulumlarda 24 ya da 26 tercih edilebilir.

Ayarlar vite.config.ts'ye taşındı (Config moved to Vite)

svelte.config.js artık okunmuyor. Eskiden config.kit.* altında duran seçenekler sveltekit() eklentisinin üst düzey seçenekleri oldu:

// vite.config.ts
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    sveltekit({
      adapter: adapter(),
      paths: { origin: 'https://example.com' },
      csrf: { trustedOrigins: ['https://checkout.example.com'] }
    })
  ]
});

Kaldırılan seçenekler: files.lib, preloadStrategy, prerender.origin, csrf.checkOrigin, vitePlugin, experimental.handleRenderingErrors ve experimental.instrumentation. experimental.tracing üst düzey tracing oldu. Yeni paths.origin seçeneği hem prerender.origin'in hem de adapter-node'daki ORIGIN ortam değişkeninin yerini alıyor. Sürüm yoklama aralığı (version.pollInterval) varsayılan olarak bir saat oldu.

$lib yerine #lib (Subpath imports)

SvelteKit artık $lib takma adını üretmiyor. Bunun yerine Node'un standart alt yol içe aktarma özelliği kullanılıyor. package.json'a şu eklenir:

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

İçe aktarmalarda dosya uzantısı da yazılmalı:

import { foo } from '#lib/foo.js'; // eskiden: '$lib/foo'

Bu değişikliğin faydası, takma adın yalnız SvelteKit'e özel olmaktan çıkması: Node, TypeScript ve diğer araçlar aynı tanımı doğrudan anlıyor.

Kaldırılan ve değişen API'ler (Removed APIs)

• $app/stores kaldırıldı: $page, $navigating, $updated yerine $app/state kullanılıyor (page.url.pathname, başında $ olmadan).
• Ortam değişkenleri: $app/environment adı $app/env oldu. $env/* modülleri kullanımdan kaldırılma sürecinde; yerine $app/env/private ve $app/env/public.
• $service-worker kaldırıldı: version $app/env'den, assets, immutable, prerendered yeni $app/manifest'ten geliyor.
• $app/paths: base, assets ve resolveRoute dışa aktarılmıyor; yerine asset() ve resolve().
• Gezinme: invalidateAll yerine refreshAll; pushState/replaceState yerine goto(url, { shallow: true, state }). goto artık bir rotaya karşılık gelmeyen adreste hata veriyor; dış bağlantılar için window.location.href kullanılmalı.
• Yardımcılar: json() ve text() yerine standart Response.json() ve new Response() öneriliyor.
• Parametre eşleştiriciler: src/params/ klasörü yerine tek bir src/params.ts dosyası ve defineParams.

Güvenlik ve hata yönetimi (Security and errors)

Güvenlik tarafında iki önemli değişiklik var. csrf.checkOrigin kaldırıldı; CSRF koruması her zaman açık ve belirli kaynaklara izin vermek için csrf.trustedOrigins kullanılıyor. Content-Type başlığı olmayan kökenler arası değiştirici istekler reddediliyor. Ödeme sağlayıcısından form geri dönüşü alan sitelerin bu listeyi doğru doldurması gerekiyor.

Hata yönetiminde handleError artık error(...) ile fırlatılanlar dahil tüm hataları alıyor ve yanıt kodunu belirlemek için status döndürebiliyor. handleValidationError kaldırıldı; doğrulama hataları kind: 'validation' ile aynı kancaya geliyor. error() fonksiyonunun ikinci argümanı artık yalnız metin olabiliyor. Çerezler cookie v2'ye geçti: çerez adları ASCII olmalı, varsayılan path '/'.

Adaptörlerde de kırıcı değişiklikler var: adapter-node paketlemeyi rolldown ile yapıyor ve yalnız derleme anında var olan statik dosyaları sunuyor (sonradan klasöre eklenen dosya 404 verir); adapter-vercel'de edge çalışma zamanı kaldırıldı; adapter-cloudflare'de platform nesnesi yerine cloudflare:workers modülü kullanılıyor.

Adım adım geçiş (Migration steps)

1. Önce en son SvelteKit 2.x sürümüne geçin; hedefli kullanımdan kaldırma uyarılarını orada görürsünüz.
2. Node.js, Vite, Svelte ve TypeScript'i asgari sürümlere yükseltin.
3. Otomatik geçişi çalıştırın:
   BashKopyala

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

   Komut kodu olabildiğince dönüştürüyor ve elle yapılacaklar için bir yapılacaklar listesi üretiyor.
4. Listeyi tamamlayın: $app/stores kullanımları, özel sunucudaki @sveltejs/kit/node/polyfills içe aktarmaları, csrf.trustedOrigins ve adaptör ayarları.
5. Ön izleme ortamında formları, oturum çerezlerini, yönlendirmeleri ve statik dosya sunumunu test edin.

Alesta WEB olarak çerçeve geçişlerinde aynı sırayı izliyoruz: önce son ara sürüm, sonra uyarıların temizlenmesi, en son ana sürüm. Next.js 16 geçişinde olduğu gibi burada da en çok zaman alan kısım otomatik araçların dönüştüremediği yönlendirme ve çerez davranışları oluyor.

Sık sorulan sorular

SvelteKit 2 desteği ne zaman bitiyor?

Duyuruda SvelteKit 2 için bir destek bitiş tarihi verilmedi. Yeni projelerde doğrudan 3 ile başlamak mantıklı.

svelte.config.js dosyamı silmem mi gerekiyor?

Evet, SvelteKit 3 bu dosyayı desteklemiyor. İçindeki ayarlar vite.config.ts'deki sveltekit() çağrısına taşınmalı; geçiş komutu bunu büyük ölçüde yapıyor.

Remote functions kullanabilir miyim?

Deneysel bayrakla kullanılabiliyor ama kararlı değil. Üretimde kullanmadan önce kararlı sürümü beklemek daha güvenli.

Svelte 5.57.1'de yeni özellik var mı?

Hayır. Svelte ekibine göre 5.57.1 yalnız hata düzeltmeleri ve ayrıştırıcı performansı içeriyor; SvelteKit 3'ün asgari Svelte sürümü olduğu için önemli.

İlgili yazılar: Next.js 16 geçiş rehberi · Node.js 26 LTS · Web yazılım hizmetleri · İletişim

Kapak fotoğrafı: JEFERSON DA PAULINO / Unsplash