sveltekit-config

SvelteKit の設定

このスキルを使うタイミング

SvelteKit の設定、ビルドパイプライン、デプロイ、パフォーマンス、画像、アクセシビリティ、SEO、デバッグ、移行に関する作業を行う際は、いつでもこのスキルを使ってください。具体的には、次のような作業が含まれます。

• アダプター（adapter-node、adapter-static、adapter-cloudflare、adapter-netlify、adapter-vercel）の選択または設定
• 本番アプリのビルド（vite build）とプレビュー（vite preview）
• 高度なルーティング（rest パラメーター、省略可能なパラメーター、マッチャー、ルートの並べ替え、ファイル名のエンコーディング）
• 高度なレイアウト（ルートグループ、@ によるレイアウトからの切り離し）
• 認証の統合パターン（セッションとトークンの比較、フックベースの認証）
• パフォーマンスの最適化（コード分割、アセットの最適化、ウォーターフォールの回避）
• 画像の扱い（@sveltejs/enhanced-img、CDN 読み込み、<picture>／<img> パターン）
• アクセシビリティ（ルートのアナウンス、フォーカス管理、lang 属性）
• SEO（タイトル、メタタグ、サイトマップ、JSON-LD）
• ブレークポイントのデバッグ（VS Code、Chrome DevTools）
• SvelteKit v1 または Sapper からの移行

ルーティング／データ／load の基本については、sveltekit-overview を参照してください。Svelte コンポーネント／runes については、svelte-runes を参照してください。

重要：ビルドとプレビュー

vite build は 2 段階で実行されます。まず Vite が最適化された本番ビルドを生成し、次にアダプターが対象プラットフォームに合わせて出力を調整します。プリレンダリングはビルド中に実行されます。

ビルド中、SvelteKit は解析のために +page/layout(.server).js を読み込みます。ビルド時に実行してはいけないコードは、$app/environment の building を使ってガードしてください。

import { building } from '$app/environment';
import { initialiseDatabase } from '$lib/server/database';

if (!building) initialiseDatabase();

export function load() { /* ... */ }

ビルド後、vite preview（または npm run preview）を実行して、本番ビルドをローカルでテストします。プレビューは Node で実行されるため、アダプター固有の動作（例：Cloudflare の platform オブジェクト）は適用されません。正確にテストするには、Cloudflare の場合は wrangler dev を、その他の場合は各プラットフォームの CLI を使用してください。

npm run build       # vite build + adapter
npm run preview     # vite preview (Node)

重要：アダプター — 用途に応じた選び方

アダプターは svelte.config.js の kit.adapter で設定します。新規プロジェクトにはデフォルトで adapter-auto が含まれており、既知のデプロイ環境（Cloudflare Pages、Netlify、Vercel、Azure SWA、SST、Google Cloud Run）に適したアダプターを選択します。対象を選んだら、そのアダプターを明示的にインストールしてロックファイルに登録してください。

対象	アダプター	備考
Node サーバー／Docker／VM	@sveltejs/adapter-node	スタンドアロンの Node サーバーです。最も柔軟です。
静的ホスティング（SSR なし）	@sveltejs/adapter-static	SSG または SPA フォールバックです。
Cloudflare Workers／Pages	@sveltejs/adapter-cloudflare	どちらにも対応する統合アダプターです。
Netlify	@sveltejs/adapter-netlify	Node 関数または Deno エッジです。
Vercel	@sveltejs/adapter-vercel	サーバーレスまたはエッジで、ISR に対応しています。

アダプターのクイックガイド：

// svelte.config.js
import adapter from '@sveltejs/adapter-node';
export default { kit: { adapter: adapter() } };

プラットフォーム固有のコンテキスト

一部のアダプターでは、event.platform を介してフック／サーバールート内でプラットフォーム情報（KV 名前空間、Durable Objects、環境変数）を公開します。型拡張は src/app.d.ts で行います。

declare global {
  namespace App {
    interface Platform {
      env: { MY_KV: KVNamespace };
    }
  }
}
export {};

環境変数には常に $env/static/private を優先してください。プリレンダリング中は $env/dynamic/* を使用できません。

重要：高度なルーティング

SvelteKit のルートはファイルシステムベースです。基本的な動的セグメント以外にも、いくつかの高度な機能があります。

Rest パラメーター — [...rest]

不定数のセグメントに一致します。src/routes/a/[...rest]/z/+page.svelte は /a/z、/a/b/z、/a/b/c/z に一致します。rest パラメーターは / 区切りのセグメントを含む文字列です。

src/routes/[org]/[repo]/tree/[branch]/[...file]/+page.svelte

カスタム 404 を表示するには、rest パラメーターを使います。error(404) を呼び出す [...path]/+page.js を追加すると、ネストされた +error.svelte が表示されます。

省略可能なパラメーター — [[lang]]

二重の角括弧で囲むと、パラメーターを省略可能にできます。[[lang]]/home は /home と /en/home の両方に一致します。省略可能なパラメーターを rest パラメーターの後に置くことはできません。

マッチング — [name=type]

src/params/ にあるマッチャーでパラメーターを制約します。

// src/params/fruit.js
/** @type {import('@sveltejs/kit').ParamMatcher} */
export function match(param) {
  return param === 'apple' || param === 'orange';
}

次に、src/routes/fruits/[page=fruit]/+page.svelte を作成します。マッチャーはサーバーとブラウザーの両方で実行されます。

並べ替え

複数のルートが一致する場合、SvelteKit は次の順に並べ替えます。

1. より具体的なルートが優先されます（パラメーターが少ないほど具体的です）
2. マッチャー（[name=type]）は制約のないルート（[name]）より優先されます
3. [[optional]] と [...rest] の優先度は最も低くなります。ただし、最後のセグメントの場合を除きます
4. 同順位の場合はアルファベット順で決まります

特殊文字のエンコード

フォルダー名では、16進エスケープ [x+nn] を使用します。/ → [x+2f]、: → [x+3a] などです。Unicode には [u+nnnn] を使用します（サロゲートペアは不要です）。

src/routes/smileys/[x+3a]-[x+29]/+page.svelte
# matches /smileys/:-)

重要：高度なレイアウト

デフォルトでは、レイアウト階層はフォルダー階層を反映します。次のパターンを使うと、階層を組み替えられます。

ルートグループ — (group)

かっこで囲まれたフォルダー名は URL に表示されません。URL 構造に影響を与えずに、複数のルートでレイアウトを共有できます。

src/routes/
├ (app)/dashboard/+page.svelte
├ (app)/+layout.svelte          # app shell
├ (marketing)/about/+page.svelte
├ (marketing)/+layout.svelte    # marketing shell
└ +layout.svelte

レイアウト階層からの切り離し — [email protected]

@<segment>（またはルートの場合は @）を末尾に追加すると、レイアウトチェーンがリセットされます。+page@(app).svelte は (app)/+layout.svelte からのみ継承します。

選択肢：+page@[id].svelte、[email protected]、+page@(app).svelte、[email protected]。

レイアウトも階層から切り離せます。[email protected] は、その配下のすべてについてルートまで戻ります。

ルートにリセットする

アプリの大部分を1つのレイアウトの下に置き、一部のルートだけをそこから切り離したい場合は、例外を除くすべてをグループ内に置きます。

src/routes/
├ (app)/...
└ admin/+page.svelte   # does NOT inherit (app) layout

重要：認証の統合

認証には、authentication（これは誰か）と authorization（何ができるか）が含まれます。

セッションとトークンの比較

• セッション：ID を DB に保存します。すぐに無効化できますが、リクエストごとに DB の参照が必要です。
• JWT トークン：自己完結型で DB の参照は不要ですが、すぐには無効化できません。レイテンシーを抑えられます。

統合パターン

src/hooks.server.js で認証 Cookie を確認し、event.locals.user に値を設定してから、+page.server.js／+server.js の load 関数で locals を読み取ります。

// src/hooks.server.js
export async function handle({ event, resolve }) {
  event.locals.user = await getUser(event.cookies.get('session'));
  return resolve(event);
}

ライブラリー

• npx sv add better-auth — Svelte CLI による Better Auth の統合
• Lucia auth guide — セッションベース認証の参考となる SvelteKit の例

SvelteKit v2 で cookies.set(...) を呼び出す際は、必ず path: '/' を指定してください。

重要：パフォーマンスの最適化

SvelteKit には、コード分割、アセットのプリロード、ファイルのハッシュ化、リクエストの集約、並列読み込み、データのインライン化、保守的な無効化、リンクのプリロードが組み込まれています。さらに最適化するには、次の方法があります。

診断

• PageSpeed Insights／Lighthouse／WebPageTest
• Chrome DevTools の Network タブと Performance タブ
• 開発モードではなく、プレビューモード（vite build の実行後）でテストします

アセット

• 画像には @sveltejs/enhanced-img を使います（ファイルサイズの小さい形式、固有の寸法）
• ファーストビューより下にある動画は preload="none" で遅延読み込みします
• フォントをサブセット化し、handle フックの preload フィルターを使って重要なフォントをプリロードします

コードサイズ

• Svelte 5 を使います（Svelte 4 より小さいサイズです）
• rollup-plugin-visualizer を使って容量の大きいパッケージを特定します
• 条件付きコードには動的な import() を優先します
• サードパーティーのスクリプトは Web Worker に移します（Partytown）

ウォーターフォールを回避する

• バックエンド呼び出しには サーバーの load 関数 を使います（クライアント → サーバー → バックエンドの連鎖を回避します）
• Promise.all／DB の結合を使ってクエリーを並列実行します
• SPA モードではウォーターフォールが発生します。代わりにプリレンダリングしてください

ホスティング

• フロントエンドをバックエンドの近くにデプロイします（またはエッジを使用します）
• HTTP/2 以降を使用できるようにします

重要：画像

Vite の組み込み処理

<script>
  import logo from '$lib/assets/logo.png';
</script>
<img alt="logo" src={logo} />

Vite はファイル名をハッシュ化し、小さなアセットをインライン化します。

@sveltejs/enhanced-img

ビルド時に画像を最適化し、avif／webp を生成して、固有の width／height を設定し（CLS を防止）、EXIF 情報を削除します。

// vite.config.js — plugin order matters
import { enhancedImages } from '@sveltejs/enhanced-img';
import { sveltekit } from '@sveltejs/kit/vite';
export default { plugins: [enhancedImages(), sveltekit()] };

使用例：

<enhanced:img src="./image.jpg" alt="..." sizes="min(1280px, 100vw)" />

生成される <picture> には、HiDPI 向けに複数の形式とサイズが含まれます。Retina ディスプレイ用に 2x のソースを指定してください。

幅のカスタマイズ：<enhanced:img src="./image.png?w=1280;640;400" /> 画像ごとの変換：<enhanced:img src="./image.jpg?blur=15" />

動的な CDN 読み込み

ビルド時に利用できない画像（CMS、DB）には、CDN ライブラリを使用します。

• @unpic/svelte — CDN に依存しません
• svelte-cloudinary — Cloudinary
• CMS 組み込み：Contentful、Storyblok、Contentstack

ベストプラクティス

• LCP 画像には fetchpriority="high" を設定し、loading="lazy" は使用しないでください
• 常に alt テキストを指定してください
• sizes では em／rem を使用しないでください
• 戦略を組み合わせてください：<meta> には Vite、ヒーロー画像には enhanced-img、ユーザーコンテンツには CDN

重要：アクセシビリティ

SvelteKit はアクセシビリティの基盤を提供しますが、アプリレベルのアクセシビリティ対応は引き続き必要です。

ルートのアナウンス

SvelteKit は、クライアント側のナビゲーションが発生するたびに <title> を読み上げるライブリージョンを挿入します。すべてのページで、<svelte:head> 内に固有で内容を説明する <title> を設定してください。

<svelte:head>
  <title>Todo List</title>
</svelte:head>

フォーカス管理

ナビゲーションのたびに、SvelteKit は <body>（または存在する場合は [autofocus] 要素）にフォーカスします。独自の動作を指定するには、afterNavigate で上書きしてください。

import { afterNavigate } from '$app/navigation';
afterNavigate(() => document.querySelector('.focus-me')?.focus());

入力欄のフォーカスを保持するには、<form> に data-sveltekit-keepfocus を使用します。プログラムからナビゲーションする場合は、goto(url, { keepFocus: true }) を使用します。

lang 属性

src/app.html で <html lang="en">（または使用する言語）を設定します。多言語サイトでは、handle 内の transformPageChunk を使用して、リクエストごとに設定します。

重要：SEO

SvelteKit には SSR、末尾のスラッシュを正規化する URL 処理、適切なデフォルト設定が備わっています。手動で必要な手順は次のとおりです。

ページごとのメタ情報

<svelte:head>
  <title>Page Title — Site Name</title>
  <meta name="description" content="..." />
  <meta property="og:title" content="..." />
  <meta property="og:description" content="..." />
  <meta property="og:image" content="..." />
  <meta property="og:type" content="website" />
  <link rel="canonical" href="https://..." />
</svelte:head>

一般的なパターンでは、load から SEO データを返し、ルートレイアウトの <svelte:head> 内に表示します。

サイトマップ

// src/routes/sitemap.xml/+server.js
export async function GET() {
  return new Response(`<?xml version="1.0" encoding="UTF-8"?>
    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
      
    </urlset>`, { headers: { 'Content-Type': 'application/xml' } });
}

JSON-LD 構造化データ

<script type="application/ld+json"> を含め、<svelte:head> 経由で挿入します。

重要：移行

SvelteKit v1 → v2

npx sv migrate sveltekit-2（古いプロジェクトでは npx svelte-migrate）を使用します。破壊的変更は次のとおりです。

• error(...) と redirect(...) はスローされなくなりました。呼び出すだけで構いません
• cookies.set/delete/serialize には path: '/' が必要です
• load 内のトップレベルの Promise は自動的に待機されません。明示的に await を使用してください
• goto は外部 URL を受け付けなくなりました（window.location.href を使用してください）
• paths は一貫して相対パスになりました（デフォルトは true）
• $app/stores は 2.12 で非推奨になりました。$app/state（Svelte 5 のルーン）に移行してください
• Svelte 4 が必要です。Node 18.13 以上が必要です
• vitePreprocess は @sveltejs/vite-plugin-svelte からインポートする必要があります

Sapper → SvelteKit

• package.json："type": "module" を追加し、polka／sapper／sirv／compression を削除します
• @sveltejs/kit とアダプターを追加します
• スクリプト：sapper build → vite build、sapper dev → vite dev、node __sapper__/build → node build
• src/template.html → src/app.html（%sapper.* プレースホルダーを置き換えます）
• ルート：routes/about/index.svelte → routes/about/+page.svelte
• _layout.svelte → +layout.svelte、_error.svelte → +error.svelte
• preload → load（API が異なります：引数は単一の event で、this.fetch はありません）
• $app/stores（または 2.12 以降では $app/state）から stores／navigating を使用します
• 正規表現によるルート → src/params/ 内のマッチャー
• sapper:prefetch → data-sveltekit-preload-data
• sapper:noscroll → data-sveltekit-noscroll
• 内部ライブラリを src/node_modules/... から src/lib に移動します

重要：デバッグ

VS Code

組み込みのデバッグターミナルは、設定なしですぐに使えます。

1. CMD/Ctrl+Shift+P → 「Debug: JavaScript Debug Terminal」
2. そのターミナルで npm run dev を実行します
3. ブレークポイントを設定し、ブラウザーで停止させます

または、.vscode/launch.json を作成します。

{
  "version": "0.2.0",
  "configurations": [
    { "command": "npm run dev", "name": "dev", "request": "launch", "type": "node-terminal" }
  ]
}

Chrome DevTools／Edge

NODE_OPTIONS="--inspect" npm run dev

サイトを開き、「Open dedicated DevTools for Node.js」アイコン（左上の Node ロゴ）をクリックします。または、chrome://inspect にアクセスします。

すぐにできる修正

• building フラグ：vite build の実行中に初期化コードが実行されないよう、1 回限りの初期化コードを if (!building) で囲みます。
• adapter-static の fallback：SPA モードでは 200.html を使います。ただし、プリレンダリングされた / と競合するため、index.html は避けてください。
• GitHub Pages：paths.base にリポジトリ名を設定し、fallback: '404.html' を指定します。static/ に .nojekyll を追加してください。
• Node のオリジン：プロキシの背後にいて「Cross-site POST form submissions are forbidden」が表示される場合は、ORIGIN 環境変数を設定します。
• XFF の深さ：N 個のプロキシの背後にいる場合は、getClientAddress() が実際のクライアント IP を返すように XFF_DEPTH=N を設定します。
• 圧縮：SvelteKit はレスポンスをストリーム配信するため、compression ではなく @polka/compression を使います。
• 本番環境の .env：本番環境では .env は自動で読み込まれません。node --env-file=.env build（Node 20.6 以降）または -r dotenv/config を使います。
• platform は開発／プレビュー時のみ：Cloudflare／Netlify／Vercel のプラットフォーム API をテストするには、それぞれの CLI（wrangler dev、netlify dev、vercel dev）を使います。
• fs が利用できない：$app/server の read を使います（デプロイ済みアセットからフェッチすることで、エッジ環境でも動作します）。
• 外部 URL への goto：代わりに window.location.href を使います。
• Cookie のパス：SvelteKit v2 では、cookies.set(...) に path: '/' を指定する必要があります。
• 末尾のスラッシュ：ホストが /a.html から /a を配信しない場合は、trailingSlash: 'always' を設定します。

注意点

• プレビューは本番環境ではありません：vite preview は Node で実行され、アダプター固有の動作を再現しません。正確なローカルテストには、プラットフォームの CLI を使います。
• adapter-auto は設定不要で使うためのものです：デプロイ先を決めたら、実際に使うアダプターをインストールしてください。そうすればロックファイルに記録され、オプションも指定できます。
• Cloudflare でのサーバーバンドルサイズ：Workers にはサイズ制限があります。制限に達した場合は、大きなライブラリをクライアント専用のインポートに移してください。
• AWS／Node 18：SvelteKit v2 には Node 18.13 以降が必要です。それより古い Node では、分かりにくいエラーが発生します。
• ISR とプリレンダリング：export const prerender = true を指定したルートでは、ISR は効果がありません。
• adapter-cloudflare-workers は非推奨です：@sveltejs/adapter-cloudflare を使ってください（wrangler の設定で assets.directory と assets.binding を指定します）。
• Svelte 4 から 5 への移行：$app/stores は非推奨です。代わりに $app/state を使います。先に Svelte を更新し、その後 SvelteKit を更新してください。
• Tailwind と <enhanced:img>：タグ名セレクターでは、コロンをエスケープするために enhanced\:img が必要です。
• チャット／SPA のような UI では data-sveltekit-noscroll に一致させる：デフォルトのページ先頭へのスクロール動作により、無限スクロールのアプリが正常に動作しなくなることがあります。
• Vite のアセットのインライン化：assetsInlineLimit（デフォルトは約 4kb）より小さいアセットは、base64 でインライン化されます。enhanced-img では svg は対象外です。

よくある質問

adapter-auto を使うべきですか？ プロトタイピングには適しています。デプロイ先を選んだら、設定できるように専用のアダプターに切り替えてください。

SPA モードとフル SSR のどちらがよいですか？ SEO とパフォーマンスの面では、adapter-static を使ったフル SSR（プリレンダリング）が最適です。SPA フォールバックは、すべてをプリレンダリングせずに静的ホスティングのみの環境へデプロイする必要がある場合に使います。SPA は SEO とパフォーマンスを損ないます。

いつプリレンダリングすればよいですか？ 訪問者ごとに同じコンテンツを返すページ（マーケティングページ、ブログ投稿、ドキュメント）です。ルートに export const prerender = true を追加してください。

本番環境でどのアダプターが使われているか、どうすれば分かりますか？ adapter-auto はビルド時に選択したアダプターをログに出力します。それ以外の場合は、svelte.config.js を確認してください。

同じ svelte.config.js を複数のアダプターで使えますか？ いいえ。アダプターごとに vite build を実行する必要があります。CI でよく使われる方法は、デプロイ先ごとのビルドマトリックスです。

Cloudflare Worker のサイズが大きくなるのはなぜですか？ バンドルの肥大化が原因です。サーバーサイドのインポートによって、大きな依存関係が取り込まれています。それらを動的な import() またはクライアント専用のインポートに移してください。

SvelteKit 2 に Svelte 5 は必要ですか？ Svelte 4 以降が必要です。$app/state と runes を使うには Svelte 5 が推奨されます。

使用例と参考資料

例

ファイル	内容
examples/build-preview.md	vite build、vite preview、ビルド時の環境変数
examples/adapter-node.md	開発／ビルド／デプロイ、カスタムサーバー、環境変数
examples/adapter-static.md	すべてのページの事前レンダリング、SPA フォールバック、GitHub Pages
examples/adapter-cloudflare.md	workers、pages、ランタイム API、環境変数
examples/adapter-netlify.md	デプロイ、エッジ関数、環境変数
examples/adapter-vercel.md	デプロイ、画像の最適化、ISR、環境変数、バージョン不整合の保護
examples/writing-adapter.md	ビルダー API を使ったカスタムアダプター
examples/advanced-routing.md	rest パラメーター、オプション、マッチャー、並べ替え、エンコード
examples/advanced-layouts.md	ネストされたレイアウト、名前付きレイアウト、エラーのリセット、グループ
examples/performance.md	コード分割、アセットの最適化、ハイドレーションの最適化
examples/images.md	enhanced-img、動的 CDN 読み込み、ベストプラクティス
examples/accessibility.md	ルートのアナウンス、フォーカス管理、lang 属性
examples/seo.md	メタタグ、OG タグ、JSON-LD、サイトマップ
examples/debugging.md	VS Code launch.json、ブラウザーのブレークポイント
examples/migration-v2.md	エラー／リダイレクトの変更、Cookie のパス、トップレベルの Promise

リファレンス

ファイル	内容
references/adapters-comparison.md	各アダプターの用途を詳しく比較したマトリックス
references/building-reference.md	vite build のオプション、プレビュー、環境変数
references/routing-advanced-reference.md	rest／オプション／マッチャー／並べ替え／エンコードの詳細
references/layouts-advanced-reference.md	ネスト／名前付き／グループ、リセット、レイアウトから抜ける方法
references/auth-reference.md	セッションとトークンの比較、統合ポイント、ライブラリー
references/performance-reference.md	最適化チェックリストの全項目
references/images-reference.md	Vite と @sveltejs/enhanced-img のリファレンス
references/a11y-reference.md	アクセシビリティのパターンとリソース
references/seo-reference.md	SEO の設定、メタタグ、構造化データ
references/migration-v1-v2-reference.md	破壊的変更の全リスト
references/migration-sapper-reference.md	Sapper から SvelteKit への完全な移行
references/debugging-reference.md	IDE／デバッガーの設定