sveltekit-overview

SvelteKit の概要

SvelteKit は Svelte の公式アプリケーションフレームワークです。ルーティング、ビルドパイプライン、サーバーランタイム、デプロイアダプターを備えており、単一の SvelteKit コードベースからウェブアプリ（SSR、SSG、SPA、MPA、モバイル、デスクトップ、組み込み）をリリースできます。

このスキルを使う場面

次のような場合にこのスキルを使います。

• npx sv create で新しい SvelteKit プロジェクトを作成する。
• レンダリングモード（SSR、SSG、SPA、MPA、ハイブリッド）を選ぶ。
• 標準的なプロジェクト構成（src/routes、src/lib、static、svelte.config.js）を理解する。
• +page.svelte、+page.js、+page.server.js、+server.js のどれを使うか判断する。
• SvelteKit のハンドラー内で Web プラットフォーム API（fetch、Request、Response、Headers、FormData、ReadableStream、URL、URLSearchParams、crypto）を使う。
• $types モジュール（PageLoad、PageServerLoad、LayoutLoad、LayoutServerLoad、RequestHandler、PageProps、LayoutProps）を使ってルートファイルに型を付ける。
• +server.js で API エンドポイントを構築する（GET / POST / PUT / PATCH / DELETE / OPTIONS / フォールバック）。
• レイアウト、エラーバウンダリー（+error.svelte）、ネストされたルーティングを設定する。

重要：Svelte と SvelteKit の使い分け

Svelte は UI コンポーネント層です。SvelteKit はそれを包むアプリケーションフレームワークです。

必要なもの	使用するもの
単一のコンポーネントをレンダリングする、既存サイトに埋め込む	Svelte のみ
ルーティング、データ読み込み、SSR、アダプターを備えたアプリを構築する	SvelteKit
SSG / SSR / SPA / MPA / サーバーレス	SvelteKit
ページ内で Svelte 5 の runes を使う	SvelteKit 内の Svelte

目安：複数の「ページ」がある場合、バックエンドが必要な場合、または SEO を重視する場合は、SvelteKit を使います。

# Pure Svelte (no routing, no SSR)
npm create vite@latest my-app -- --template svelte
# Full SvelteKit app (routing + SSR + adapters)
npx sv create my-app

重要：プロジェクトの作成（npx sv create）

# Minimal
npx sv create my-app
cd my-app
npm install
npm run dev    # http://localhost:5173

便利なフラグ（sv CLI のドキュメントを参照）：

# Non-interactive with explicit choices
npx sv create my-app \
  --template minimal --types ts --no-add-ons --install npm

# Pick a template
npx sv create my-app --template demo   # demo | minimal | library

# Add common add-ons later
npx sv add prettier eslint vitest playwright tailwindcss

CLI は次のファイルをひな形として生成します：package.json、svelte.config.js、vite.config.js、tsconfig.json、src/app.html、src/routes/+page.svelte、および（オプションに応じて）hooks.client.js、hooks.server.js、service-worker.js。

重要：プロジェクトの種類を選ぶ判断表

レンダリング設定はアダプターごと、ページごとに構成します（export const prerender = true、export const ssr = false、export const csr = false）。複数の設定を組み合わせるのが一般的です。

プロジェクトの種類	アダプター	設定	用途
デフォルト（SSR + CSR）	任意	なし	ほとんどのアプリ。初回表示は SSR、ページ遷移後は CSR。
静的サイト生成（SSG）	adapter-static	prerender = true（ルートまたはページごと）	ドキュメント、ブログ、マーケティング。
シングルページアプリ（SPA）	フォールバック付きの adapter-static	ssr = false	アプリシェル + JSON バックエンド、SEO 不要。
マルチページアプリ（MPA）	任意	<body data-sveltekit-reload> + csr = false	JavaScript を抑えた、サーバー主導のページ。
分離したバックエンド	adapter-node またはサーバーレス	server ファイルを使わない	バックエンドが Go/Rust/Java/PHP の場合。
サーバーレス	adapter-vercel / adapter-netlify / adapter-cloudflare	なし	Vercel / Netlify / Cloudflare へのデプロイ。
独自サーバー / VPS	adapter-node	なし	セルフホストの Node サーバー。
コンテナ（Docker/LXC）	adapter-node	なし	コンテナイメージ内で実行。
ライブラリ	@sveltejs/package アドオン	「library」テンプレートを選択	Svelte コンポーネントをパッケージとして公開する。
オフライン / PWA	任意	src/service-worker.js	オフライン対応アプリ。
モバイル	adapter-static	bundleStrategy: 'single'	Tauri または Capacitor でラップする。
デスクトップ	adapter-static	bundleStrategy: 'single'	Tauri / Wails / Electron でラップする。
ブラウザー拡張機能	adapter-static またはコミュニティ製アダプター	manifest + 拡張機能の設定	Chrome / Firefox 拡張機能。
組み込みデバイス	任意	bundleStrategy: 'single'	テレビ / マイクロコントローラー（同時リクエストが少ない場合）。

重要：プロジェクト構成

my-project/
├ src/
│ ├ lib/
│ │ ├ server/      # server-only lib (use $lib/server alias)
│ │ └ [your libs]  # client-safe libs (use $lib alias)
│ ├ params/        # param matchers
│ ├ routes/        # filesystem router (one folder per route)
│ ├ app.html       # HTML template (placeholders: %sveltekit.head% etc.)
│ ├ error.html     # static fallback error page
│ ├ hooks.client.js
│ ├ hooks.server.js
│ ├ service-worker.js
│ └ instrumentation.server.js
├ static/          # served verbatim (robots.txt, favicon.ico)
├ tests/           # Playwright tests (if added)
├ package.json
├ svelte.config.js
├ tsconfig.json
└ vite.config.js

主なルール：

• $lib → src/lib（どこからでもインポートできます）。
• $lib/server → src/lib/server（サーバー専用です。SvelteKit はクライアントからのインポートをブロックします）。
• src/routes で URL ツリーを定義します。各フォルダーがルートで、+page.svelte があるとページになります。
• src/routes または src/app.html の配下にないものはすべて任意です。
• static/ よりも import でアセットを読み込む方法を優先してください（Vite がハッシュを付与します）。

重要：svelte.config.js

最小限の設定は空のオブジェクトです。svelte.config.js は、kit、preprocess、compilerOptions などを設定する SvelteConfig オブジェクトをエクスポートします。

// svelte.config.js
import adapter from '@sveltejs/adapter-auto';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter(),
    alias: {
      $components: 'src/lib/components',
      $utils: 'src/lib/utils'
    }
  }
};

export default config;

一般的な設定を 8 種類以上紹介しています。examples/svelte-config.md を参照してください。

重要：Web 標準（Fetch / FormData / Streams / URL / Web Crypto）

SvelteKit は「プラットフォームを使用」します。ブラウザー標準の API は、load 関数、+server.js ハンドラー、フックで利用できます。SvelteKit は Node ベースのアダプターでこれらの API をポリフィルします。

API	SvelteKit での使用箇所
fetch	load、フック、+server.js、サーバーとクライアントの両方
Request	フックと +server.js の event.request
Response	+server.js ハンドラーと fetch() の戻り値
Headers	event.request.headers、Response.headers
FormData	フォーム送信：await event.request.formData()
ReadableStream	レスポンス本文（ストリーミング、SSE）
URL	event.url、page.url、beforeNavigate／afterNavigate
URLSearchParams	url.searchParams.get('foo')
crypto	crypto.randomUUID()、CSPRNG、ハッシュ化

特記事項：load 関数と +server.js 内では、fetch は相対 URL を受け付け、認証情報を自動的に引き継ぎます。それ以外では、Cookie／ヘッダーを明示的に渡してください。

重要：ルーティング（+page、+layout、+server、+error、$types）

ファイルシステムがルーターです。ルートファイルは + で始まります。

ファイル	用途
+page.svelte	ページの UI です。
+page.js	ユニバーサル load 関数（サーバーとクライアント）。
+page.server.js	サーバー専用の load とフォーム actions。
+layout.svelte	ページとネストされたレイアウトを包みます。
+layout.js／+layout.server.js	レイアウトのデータ読み込み。
+server.js	API エンドポイント（HTTP メソッドのハンドラーをエクスポートします）。
+error.svelte	ルートごとのエラーバウンダリー。
*.js（その他）	無視されます。コンポーネントやユーティリティは同じディレクトリに配置してください。

覚えておくべき 3 つのルール：

1. すべてのルートファイルはサーバーで実行できます。
2. +server.js を除くすべてのルートファイルはクライアントで実行されます。
3. +layout と +error は、そのディレクトリとすべてのサブディレクトリに適用されます。

+page の 3 つのファイル

<script>
  /** @type {import('./$types').PageProps} */
  let { data } = $props();
</script>

<h1>{data.title}</h1>

// src/routes/blog/[slug]/+page.js  -- universal load
/** @type {import('./$types').PageLoad} */
export function load({ params }) {
  return { title: params.slug };
}

// src/routes/blog/[slug]/+page.server.js  -- server-only
import { error } from '@sveltejs/kit';
/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
  const post = await db.posts.find(params.slug);
  if (!post) error(404, 'not found');
  return { post };
}

+layout の 3 つのファイル

レイアウトはページを包みます。ルートの +layout.svelte は必ず children をレンダリングする必要があります。

<script>
  let { children } = $props();
</script>
<nav><a href="/">Home</a></nav>
{@render children()}

+server.js（API エンドポイント）

// src/routes/api/random-number/+server.js
import { json, error } from '@sveltejs/kit';

/** @type {import('./$types').RequestHandler} */
export function GET({ url }) {
  const min = Number(url.searchParams.get('min') ?? 0);
  const max = Number(url.searchParams.get('max') ?? 1);
  if (max <= min) error(400, 'invalid range');
  return json({ value: min + Math.random() * (max - min) });
}

ハンドラー：GET、POST、PUT、PATCH、DELETE、OPTIONS、HEAD に加え、それ以外すべてを受け取る特別な fallback があります。

+error.svelte

<script>
  import { page } from '$app/state';
</script>
<h1>{page.status} — {page.error.message}</h1>

SvelteKit はツリーを上方向にたどり、最も近い +error.svelte を探します。見つからない場合は、静的な src/error.html が使用されます。

$types

SvelteKit は各ルートファイルに対して ./$types.d.ts を自動生成します。型安全性のために使用してください。

型	使用箇所
PageLoad	+page.js
PageServerLoad	+page.server.js
LayoutLoad	+layout.js
LayoutServerLoad	+layout.server.js
RequestHandler	+server.js
PageProps	+page.svelte（{ data, params, form }）
LayoutProps	+layout.svelte（{ data, children }）
PageData、LayoutData、ActionData	旧式または用途を限定した型付け

VS Code と Svelte 拡張機能を使用すると、型が推論されるため、明示的な型注釈は省略できます。

クイック修正

• モジュール $lib が見つからない — svelte.config.js にはデフォルトで $lib エイリアスが含まれています。svelte.config.js が正しい設定を拡張していることと、少なくとも一度 npm run dev を実行したことを確認してください。
• +page.server.js のデータが表示されない — ファイル名が EXACTLY +page.server.js（+ を含む）であることを確認してください。
• +layout がネストされない — レイアウトのテンプレート内のどこかで {@render children()} を呼び出す必要があります。
• 動的パラメーターで 404 が発生する — [slug] というフォルダー名でパラメーターが作成されます。[[...rest]] は「rest」パラメーター（貪欲マッチ）です。
• ハイドレーションの不一致に関する警告 — 通常は、サーバーとクライアントで異なる値を描画する Date.now() / Math.random() が原因です。onMount または +page.server.js に移してください。
• Cannot import $lib/server into client code — src/lib/server 以下のファイルはサーバー専用です。共有コードは src/lib に移してください。
• サービスワーカーが更新されない — src/service-worker.js のバージョンを上げてください（ビルド時のキャッシュ無効化に使われます）。
• 開発時に body の拡張に関する警告が表示される — app.html では %sveltekit.body% を <body> に直接ではなく、<div> の中に配置してください。
• Cannot read properties of undefined (reading 'request') — ハンドラーで event を分割代入していないか、export async function POST(event) / GET({ request, url }) の宣言を忘れています。
• JSDoc で型エラーが発生する — tsconfig.json が ./.svelte-kit/tsconfig.json を extends していることを確認してください。

注意点

• +page.js はサーバーとクライアントの両方で実行されます。シークレットや DB 呼び出しを記述せず、+page.server.js を使用してください。
• +page.server.js から返されるデータは devalue でシリアライズされます。関数／クラスインスタンス／Map／Set は明示的に変換する必要があります。
• +server.js ファイルは +layout.svelte でラップされません。生のレスポンスを返します。横断的な処理には handle フックを使用してください。
• +error.svelte は +server.js や handle フックでスローされたエラーには使用されません。そのフォールバックには src/error.html を使用してください。
• ルートレイアウトで csr = false にすると、クライアントルーターを含め、ページ上のすべての JavaScript が削除されます。リンクをクリックするとページ全体が再読み込みされます。
• ルートレイアウトで prerender = true にすると、すべてのルートがプリレンダリングされます。ページごとに prerender = false を指定して上書きできます。
• <a href="/foo"> はクライアントルーターを使用します。サーバーナビゲーションを強制するには、<a href="/foo" data-sveltekit-reload> を使用してください。
• キーが存在しない場合、URLSearchParams.get() は undefined ではなく null を返します。
• +server.js の event.url は完全な URL です。クライアント側の page.url も完全な URL です。load の特別な fetch では相対 URL が使えます。
• 動的セグメントが / をまたいでマッチするのは、rest パラメーター [...rest] を使用した場合のみです。
• <body> に要素を直接挿入するブラウザー拡張機能は、ハイドレーションを壊すことがあります。%sveltekit.body% は <div> の中に配置してください。

FAQ

Q: TypeScript は必要ですか？ いいえ。npx sv create を使うと、JavaScript のみのプロジェクトをスキャフォールドできます。JSDoc の型も引き続き使え、型安全性を確保できます。

Q: SvelteKit で Svelte 5 のルーンを使えますか？ はい。SvelteKit 2.20+ は Svelte 5 をサポートしています。通常どおり $state、$derived、$props、$effect を使用してください。

Q: +page.server.js から自分のバックエンドを呼び出すにはどうすればよいですか？ fetch を使います（load 内では、SvelteKit 専用の fetch が Cookie を保持し、相対 URL を受け付けます）。load の外では、cookie／authorization ヘッダーを明示的に渡してください。

Q: +page.js と +page.server.js を併用できますか？ いいえ。同じルートには、どちらか一方を使います。機密データを扱う場合は、+page.server.js を優先してください。

Q: API キーはどこに保存すればよいですか？ サーバー専用の環境変数を $env/static/private（ビルド時にインライン化）または $env/dynamic/private（実行時に読み込み）に保存します。プライベートな環境変数をクライアントコードに公開しないでください。

Q: error(404) と throw error(404) の違いは何ですか？ error() は特殊なオブジェクトを返します。これをスローしないでください。error(404, 'msg') を呼び出すだけで、残りは SvelteKit が処理します。

Q: ページでクエリパラメーターを取得するにはどうすればよいですか？ $page.url.searchParams.get('foo')（Svelte 4 のストア）または page.url.searchParams.get('foo')（Svelte 5 で $app/state を使用）を使います。

Q: 静的サイトのみを作成できますか？ はい。adapter-static をインストールし、ルートレイアウト（またはページごと）で prerender = true を設定します。ビルド出力は通常の HTML です。

Q: SvelteKit は Next.js／Nuxt とどう違いますか？ ファイルベースのルーターで、デフォルトでは SSR の後に CSR を行い、組み込みの API 形式はありません。エンドポイントには +server.js を記述します。アダプターは公式に提供され、適切に保守されています。

例とリファレンス

例

ファイル	説明
examples/README.md	すべての例の一覧
examples/project-creation.md	npx sv create、--template、--types、--add、--install
examples/project-types.md	各プロジェクトタイプとアダプター＋設定スニペット
examples/project-structure.md	src/、ルート、static、package.json、svelte.config.js
examples/svelte-config.md	一般的な svelte.config.js の設定（preprocess、kit、alias）
examples/web-standards.md	認証情報付き fetch、Request、Response、FormData、ストリーム、URL
examples/routing-pages.md	+page.svelte、+page.js、+page.server.js、params、レイアウト
examples/routing-server.md	+server.js の GET／POST／PUT／DELETE、コンテンツネゴシエーション、フォールバック

リファレンス

ファイル	説明
references/README.md	すべてのリファレンスの一覧
references/project-types-reference.md	すべてのプロジェクトタイプの完全な判断マトリックス
references/project-structure-reference.md	標準的なプロジェクト構成に含まれるすべてのファイル
references/web-standards-reference.md	SvelteKit における Fetch／Request／Response／FormData／Streams／URL／Web Crypto
references/routing-reference.md	+page、+layout、+server、+error、$types のリファレンス