SvelteKit 3.0が公開、設定はviteへ集約し$libは#libに

SvelteKit 3.0が公開、設定はviteへ集約し$libは#libに ニュース

SvelteKit 3.0が2026年10月1日に公開されました。Svelteチームの公式ブログによると、設定ファイルはsvelte.config.jsからvite.config.tsへ移り、$libのエイリアスは#libに変わります。移行ガイドが示す最低要件は、Node.js 22.17、TypeScript 6、Svelte 5.57.1、Vite 8.0.12、@sveltejs/vite-plugin-svelte 7です。既存のSvelteKit 2系のアプリは、設定やimportの書き換えが必要になると考えられます。この記事では、移行前に確かめたい点と、自動移行コマンドの使いどころを整理します。

svelte.config.jsが使えなくなった

SvelteKit 3ではsvelte.config.jsが非対応になり、設定はvite.config.ts（JavaScript版ならvite.config.js）のsveltekit()プラグインのオプションに書きます。Publickeyは、Svelteのコンパイラ設定、SvelteKitの設定、Viteの設定を近い場所で管理できるようになった点を挙げています。

移行ガイドによると、次のオプションは削除されました。

  • files.lib
  • experimental.handleRenderingErrors
  • experimental.instrumentation
  • vitePlugin
  • preloadStrategy
  • prerender.origin
  • csrf.checkOrigin

後継として、csrf.checkOriginにはcsrf.trustedOrigins、prerender.originにはpaths.originが用意されました。experimental.tracingは、トップレベルのtracingオプションになりました。上のオプションを設定に書いているプロジェクトは、移行後の設定を見直すことになります。

$libが#libに。拡張子も書く

自動生成されていた$libエイリアスは、Node.jsのサブパスインポートを使う#libに変わりました。定義はpackage.jsonのimportsで行います。移行ガイドの例は次のとおりです。

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

コード側では$libを#libに置き換え、拡張子（.jsや.ts）を明示します。たとえばimport { foo } from '$lib/foo'はimport { foo } from '#lib/foo.js'になります。拡張子の指定が必要なので、置換後にビルドで確かめるのが確実です。

$app/*・CSRF・エラー処理の破壊的変更

移行ガイドには、設定とエイリアスのほかにも多くの破壊的変更が載っています。影響が大きそうなものを挙げます。

  • $app/environmentは$app/envに改名。$app/storesは削除され、$app/stateを使う。
  • $app/pathsのbase・assets・resolveRouteは削除され、asset()とresolve()を使う。
  • $app/navigationのinvalidateAllは非推奨になり、refreshAllを使う。
  • json()とtext()は非推奨。Response.json()やnew Response()を使う。
  • CSRF保護は常に有効。許可するオリジンはcsrf.trustedOriginsで指定する。
  • error()の第2引数は文字列のみで、追加のプロパティは第3引数に渡す。
  • handleValidationErrorは削除され、検証エラーはhandleErrorにkind: 'validation'として渡る。
  • 公式アダプターはすべてSvelteKit 3が必要。adapter-vercelはedgeランタイムをサポートしない。

とくにCSRFは、外部からPOSTを受けるアプリで動作が変わる可能性があります。移行ガイドによると、Content-Typeヘッダーのない、異なるオリジンからの変更系リクエストは拒否されます。また、このチェックはローカル開発では働かないとされているため、手元で動いても安心できません。adapter-nodeで使っていた環境変数ORIGINはpaths.originに置き換わっているので、リバースプロキシの背後で動かしているアプリも確認が必要です。

移行は、2.xの最新版に上げてからコマンドを実行する

公式ブログと移行ガイドが示す移行コマンドは、次のとおりです。

npx sv migrate sveltekit-3

公式ブログの例では--tasks all --confirmが付いています。多くの破壊的変更は自動で書き換えられ、自動化できない部分はTODOリストとして出力されます。移行ガイドは、先に最新の2.xへ上げておくと、対象箇所に警告が出て作業しやすいと説明しています。新規作成はnpx sv create my-new-appです。

手順にすると、次のようになります。

  1. Node.js、TypeScript、Svelte、Vite、vite-plugin-svelteのバージョンが、最低要件を満たしているかを確認する。
  2. SvelteKit 2系の最新版に上げ、出た警告を片づける。
  3. ブランチを切って、npx sv migrate sveltekit-3を実行する。
  4. 出力されたTODOを処理し、ビルドとテストを通す。
  5. CSRFの設定（本番相当の環境で確認）と、アダプターのバージョンを確認する。

Remote FunctionsとAsync Svelteは、まだ実験段階

公式ブログによると、Remote Functionsは準備中で、チームの最優先課題です。クライアントとサーバーの間で、安全かつ効率的で、型安全な通信を行うためのユーティリティ群で、利用にはAsync Svelteが必要です。公式ブログによると、Async Svelteは現時点でexperimentalフラグが必要です。移行ガイドでは、リモート関数を使うにはexperimental.remoteFunctionsを有効にする必要があるとされています。本番に入れるかどうかは、フラグが外れてから決めるのが無難でしょう。

Vite 8とアダプターの対応を見てから上げる

個人的には、要件のVite 8が最大のハードルだと考えます。SvelteKitだけの話ではなく、プロジェクト全体のビルド周りを動かすことになるので、使っているViteプラグインが8系に対応しているかを先に確かめたいところです。設定をVite側に書く方式は2.62から使えるとされているので、2.xのうちに設定の移動と#libへの置き換えを済ませておけば、3.0への切り替えは依存関係の更新が中心になります。adapter-nodeで運用しているなら、環境変数ORIGINの扱いの変更が、デプロイ手順に直接響きます。外部からPOSTを受けるアプリは、CSRFのチェックがローカルでは働かない点を踏まえ、本番相当の環境で確かめてから切り替えるのが安全でしょう。新規プロジェクトなら、はじめから3.0で始めるのが素直です。

参考にした情報

2026年10月18日時点の情報です。

タイトルとURLをコピーしました