SvelteKit 3 tuli jakoon – automaattinen siirto jättää silti TODO-listan

Svelten julkaisutiedotteen mukaan SvelteKit 3.0 julkaistiin 1. lokakuuta 2026. Vanhan sovelluksen siirtoon annettu komento npx sv migrate sveltekit-3 --tasks all --confirm muuttaa koodia automaattisesti siltä osin kuin pystyy ja jättää loppuun TODO-merkintöjä. Tuotantopäivitys edellyttää niiden ratkaisemista sekä sovelluksen toiminnan testaamista.

SvelteKit 3 siirtää projektin asetuksia Vite-konfiguraatioon ja nostaa työkaluketjun vähimmäisversioita, kuten iThomen uutinen kertoo. Kehittäjälle keskeinen ero kulkee tiedostojen automaattisen muokkauksen ja ajonaikaisen käyttäytymisen välillä: migraattori voi korjata tuonteja, mutta se ei yksin osoita, toimivatko navigointi, lomakkeet ja käyttöönotto vanhan sovelluksen odottamalla tavalla.

Siirto alkaa vanhan version varoituksista

Svelten siirto-ohje suosittelee päivittämään sovelluksen ensin uusimpaan SvelteKit 2.x -versioon, jotta poistuvista ominaisuuksista saa kohdennetut varoitukset. SvelteKit 3:n vähimmäisvaatimukset ovat Node 22.17, TypeScript 6, Svelte 5.57.1, Vite 8.0.12 ja @sveltejs/vite-plugin-svelte 7. Versiot on huomioitava myös jatkuvassa integraatiossa ja rakennusympäristössä: paikallisesti onnistuva asennus ei kerro, millä Node- ja Vite-versioilla julkaisu rakennetaan.

Ennen migraattorin ajoa nykyinen toimiva tila kannattaa tallentaa versionhallintaan ja kirjata vanhan version varoitukset. Sen jälkeen siirtokomennon voi ajaa erillisessä haarassa ja verrata sen muuttamia tiedostoja lähtötilaan. TODO-merkinnät ovat nimenomaisia käsin ratkaistavia kohtia; niiden lisäksi on katsottava muutoksia, joiden vaikutus näkyy vasta sovelluksen käydessä.

Konfiguraatio ja tuonnit vaihtavat paikkaa

Vanha svelte.config.js ei enää toimi SvelteKitin asetusten paikkana. Sovitin, Kit-asetukset ja tarvittavat kääntäjäasetukset annetaan sveltekit-lisäosalle vite.config.js- tai vite.config.ts-tiedostossa. Jos projektissa on ympäristökohtaisia asetuksia, tarkistuksen kohteena on lopullinen Vite-konfiguraatio: tiedoston siirtyminen ei vielä kerro, että kaikki vanhat arvot päätyivät oikeaan kohtaan.

Myös automaattisesti luotu $lib-alias poistuu. Sen tilalle määritellään package.json-tiedoston imports-kentässä #lib, joka perustuu Noden paketin alipolkujen tuonteihin. Uusissa tuonneissa on käytettävä yksiselitteisiä polkuja ja tiedostopäätteitä; pelkkä aliaksen nimen vaihtaminen voi jättää hakemistoon osoittavan tuonnin ratkaisematta. Tyyppitarkistus ja tuotantorakennus paljastavat tällaiset virheet, ja sovelluksen omat skriptit sekä testit on käytävä läpi, jos ne käyttävät vanhaa aliasta.

Navigointi ja palvelinvastaukset vaativat toimintatestit

Matalassa navigoinnissa pushState- ja replaceState-kutsut ovat vanhentuneita. Niiden sijaan käytetään goto-kutsua ja tilanteeseen sopivia shallow-, state- ja replace-valintoja. Muutos ei ole pelkkä uudelleennimeäminen: goto hylkää osoitteen, joka ei ratkea sovelluksen omaksi reitiksi, ja ulkoiseen osoitteeseen siirrytään selaimen tavallisella navigoinnilla. Matala navigointi käynnistää nyt myös navigointikoukut, joten koukuissa olevat ehdot voivat vaikuttaa aiemmin huomaamattomiin reittimuutoksiin.

Palvelinpuolella evästeen path-arvon uusi oletus on sivuston juuri. Aiemmassa SvelteKitissä path piti määrittää evästettä asetettaessa; päivityksen yhteydessä lisätty tai pois jätetty arvo on silti syytä tarkistaa, jos istunnon pitää rajoittua tietylle polulle. Tehostettujen lomakkeiden epäonnistumisvastaukset käyttävät nyt fail-kutsulle annettua HTTP-tilakoodia aiemman onnistumiskoodin sijaan. Muutos näkyy erityisesti testeissä ja koodissa, joka tulkitsee vastauksen tilaa.

Virheenkäsittelyssä handleError saa nyt myös error-apufunktiolla luodut odotetut virheet. Error-kutsun toiseksi argumentiksi annetaan merkkijono, ja mahdolliset lisätiedot siirtyvät kolmanteen argumenttiin. Jos sovellus kirjaa virheitä keskitetysti tai muokkaa virhesivun tietoja, odotettu virhe ja renderöinnissä syntyvä virhe on tarkistettava erikseen.

Tuotantosovitin voi muuttaa lopputulosta

Kaikki Svelten omat sovittimet edellyttävät SvelteKit 3:a, joten sovittimen päivitys kuuluu samaan muutokseen kuin sovelluskehyksen päivitys. adapter-node ei enää käytä ORIGIN-ympäristömuuttujaa; tarvittava julkinen alkuperäosoite asetetaan paths.origin-arvolla Vite-konfiguraatiossa. Sovitin tallentaa staattisten tiedostojen luettelon rakennusvaiheessa, joten myöhemmin tuloshakemistoon lisätyt tiedostot eivät tule sen kautta tarjolle.

Alustakohtaiset muutokset ovat erilaisia. Cloudflare-sovittimessa osa aiemmin platform-oliosta haetuista työntekijäympäristön tiedoista löytyy uusista sijainneista. Vercel-sovitin ei enää tue edge-ajoympäristöä, ja Netlify-sovittimen komentorivillä tehtävä käyttöönotto sekä esikatselu edellyttävät päivitettyä Netlify CLI:tä. Siksi onnistunut yleinen tuotantorakennus on vasta osa tarkistusta: esikatselun on käytettävä samaa sovitinta ja alustaa kuin varsinainen julkaisu.

Etäfunktiot pysyvät kokeellisina. Niitä käyttävässä sovelluksessa on edelleen otettava käyttöön sekä remoteFunctions-asetus että Svelten kokeellinen async-asetus. Pääversion julkaisu tai migraattorin onnistunut suoritus ei muuta tämän ominaisuuden tilaa.

Missä automaation jäljiltä on suurin riski?

Ennen tuotantoon vientiä tarkistukset kannattaa kohdistaa kohtiin, joissa koodin muuttuminen ja käyttäjälle näkyvä toiminta eroavat toisistaan:

• Rakennusketju: puuttuva vähimmäisversio näkyy asennuksessa, tyyppitarkistuksessa tai rakennuksessa. Aja ne puhtaassa ympäristössä samoilla riippuvuuksilla kuin julkaisu.
• Tuonnit ja asetukset: ratkaisematon #lib-polku tai väärään paikkaan siirtynyt asetus voi pysäyttää rakennuksen tai muuttaa sovelluksen toimintaa. Vertaa migraattorin muutoksia vanhaan konfiguraatioon ja käy TODO-merkinnät läpi.
• Reitit ja vastaukset: vanhat navigointikutsut, evästeen polku sekä lomakkeen ja virhekäsittelyn tilakoodit voivat muuttaa ajonaikaista käyttäytymistä. Kokeile keskeiset reitit, istunnot ja epäonnistuvat lomakelähetykset.
• Käyttöönotto: sovitinkohtainen muutos voi ilmetä vasta kohdealustalla. Tarkista julkinen alkuperäosoite, staattiset tiedostot ja tarvittava ajonaikainen ympäristö tuotantoa vastaavassa esikatselussa.

Versionvaihdon julkaisukelpoisuus ratkeaa lopulta siinä esikatselussa: jos reitit, istunnot ja lomakkeet toimivat oikealla sovittimella TODO-kohtien ratkaisemisen jälkeen, migraattorin tekemä työ on saanut tarvittavan ajonaikaisen tarkistuksen.

Lue myös:

• MailerLite vai Brevo? Listan koko ja lähetystiheys ratkaisevat hinnan
• invideo rakentaa ääniraidan pyynnöstä – muokkaus vie silti krediittejä
• Osoite näkyy Google-haussa – poistopyyntö ei silti pyyhi lähdesivua