Svelte入門：SvelteKitでのCloudflareページ

よっしー

こんにちは。よっしーです(^^)

今日は、SvelteKitでのCloudflareページについて解説しています。

背景
Cloudflareページ
比較
使い方
Options
1. routespermalink
2. platformProxypermalink
デプロイ
ランタイムAPIs
ローカルテスト
備考
おわりに

背景

SvelteKitでのCloudflareページについて調査する機会がありましたので、その時の内容を備忘として記事に残しました。

Cloudflareページ

Cloudflare Pagesにデプロイするには、adapter-cloudflareを使用してください。

このアダプターは、adapter-autoを使用する際にデフォルトでインストールされます。Cloudflare Pagesを継続して使用する予定がある場合は、adapter-autoから直接このアダプターに切り替えることができます。これにより以下の利点があります：

ローカル開発時にCloudflare Workers特有の値がエミュレートされます。
型宣言が自動的に適用されます。
Cloudflare特有のオプションを設定する機能が提供されます。

これらの利点により、Cloudflare Pages向けの開発がより効率的になり、Cloudflareの機能をより活用しやすくなります。

比較

adapter-cloudflare – すべてのSvelteKit機能をサポートします。Cloudflare Pages向けにビルドします。
adapter-cloudflare-workers – すべてのSvelteKit機能をサポートします。Cloudflare Workers向けにビルドします。
adapter-static – クライアントサイドの静的アセットのみを生成します。Cloudflare Pagesと互換性があります。

各アダプターの主な特徴と違いを視覚的に比較しています。adapter-cloudflareとadapter-cloudflare-workersは全てのSvelteKit機能をサポートしていますが、ビルド対象が異なります。一方、adapter-staticは機能が制限されていますが、静的ホスティングに適しており、Cloudflare Pagesとの互換性があります。

プロジェクトの要件に応じて、最適なアダプターを選択することが重要です。例えば、動的な機能が必要な場合はadapter-cloudflareやadapter-cloudflare-workersが適していますが、完全に静的なサイトであればadapter-staticで十分かもしれません。

使い方

npm i -D @sveltejs/adapter-cloudflare でインストールし、アダプターを svelte.config.js に追加します。

// svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';

export default {
	kit: {
		adapter: adapter({
			// See below for an explanation of these options
			routes: {
				include: ['/*'],
				exclude: ['<all>']
			},
			platformProxy: {
				configPath: 'wrangler.toml',
				environment: undefined,
				experimentalJsonConfig: false,
				persist: false
			}
		})
	}
};

Options

routespermalink

adapter-cloudflareによって生成される_routes.jsonファイルをカスタマイズすることができます。

includeは関数を呼び出すルートを定義し、デフォルトは['/*']です。
excludeは関数を呼び出さないルートを定義します。これはアプリの静的アセットを提供するためのより高速で安価な方法です。この配列には以下の特別な値を含めることができます：
<build> アプリのビルド成果物（Viteによって生成されたファイル）を含みます
<files> staticディレクトリの内容を含みます
<prerendered> プリレンダリングされたページのリストを含みます
<all> （デフォルト）上記のすべてを含みます

includeとexcludeのルールを合わせて最大100個まで設定できます。通常はroutesオプションを省略できますが、例えば<prerendered>パスがこの制限を超える場合、自動生成された['/articles/foo', '/articles/bar', '/articles/baz', ...]の代わりに'/articles/*'を含むexcludeリストを手動で作成すると便利かもしれません。

platformProxypermalink

ローカルバインディングのエミュレートされたplatform.envの設定です。オプションの完全なリストについては、WranglerのAPI文書のgetPlatformProxyを参照してください。

デプロイ

Cloudflare Pagesを始めるには、「Get Started Guide」に従ってください。

これらの設定は、Cloudflare PagesでSvelteKitプロジェクトを正しくデプロイするために重要です。各設定項目について簡単に説明します：

Framework preset（フレームワークプリセット）: 「SvelteKit」を選択することで、Cloudflare PagesがSvelteKitプロジェクトとして認識し、適切な設定を自動的に適用します。
Build command（ビルドコマンド）: npm run build または vite build を使用します。これらのコマンドはプロジェクトをビルドし、デプロイ可能な形式に変換します。
Build output directory（ビルド出力ディレクトリ）: .svelte-kit/cloudflare を指定します。これは、SvelteKitがCloudflare Pages用にビルドしたファイルを出力するディレクトリです。

これらの設定を正しく行うことで、SvelteKitプロジェクトがCloudflare Pages上で適切に動作するようになります。

ランタイムAPIs

env オブジェクトには、KV/DO 名前空間などで構成されるプロジェクトのバインディングが含まれています。これは、コンテキスト、キャッシュ、cf とともにプラットフォームプロパティを介して SvelteKit に渡されるため、フックとエンドポイントでアクセスできます。

export async function POST({ request, platform }) {
	const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
}

環境変数には、SvelteKit の組み込み $env モジュールを使用することをお勧めします。

バインディングの型宣言を含めるには、src/app.d.ts でそれらを参照します。

// src/app.d.ts
declare global {
	namespace App {
		interface Platform {
			env?: {
				YOUR_KV_NAMESPACE: KVNamespace;
				YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
			};
		}
	}
}

export {};

ローカルテスト

platform プロパティ内のCloudflare Workers特有の値は、開発モードとプレビューモード中にエミュレートされます。ローカルバインディングは wrangler.toml ファイルの設定に基づいて作成され、開発とプレビュー中に platform.env を設定するために使用されます。バインディングの設定を変更するには、アダプター設定の platformProxy オプションを使用してください。

ビルドのテストには、wrangler バージョン3 を使用する必要があります。サイトをビルドした後、次のコマンドを実行してください：

wrangler pages dev .svelte-kit/cloudflare

備考

関数のデプロイメントについて：
プロジェクトのルートにある /functions ディレクトリ内の関数は、デプロイメントに含まれません。デプロイメントは単一の _worker.js ファイルにコンパイルされます。代わりに、関数はSvelteKitアプリのサーバーエンドポイントとして実装する必要があります。
_headers と _redirects ファイルの使用：
Cloudflare Pages特有の _headers と _redirects ファイルは、静的アセット（画像など）のレスポンスに使用できます。これらのファイルは /static フォルダに配置します。
動的レンダリングされたレスポンスの制限：
ただし、これらのファイルはSvelteKitによって動的にレンダリングされるレスポンスには効果がありません。カスタムヘッダーやリダイレクトレスポンスは、サーバーエンドポイントから返すか、handle フックを使用して設定する必要があります。