Svelte入門：SvelteKitでのCloudflare Workers

よっしー

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

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

背景
Cloudflare Workers
使用方法
オプション
1. config
2. platformProxy
基本設定
カスタム設定
ランタイム API
ローカルでのテスト
トラブルシューティング
1. Workerのサイズ制限
2. ファイルシステムへのアクセス
おわりに

背景

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

Cloudflare Workers

Cloudflare Workers にデプロイするには、adapter-cloudflare-workers を使用します。

特にadapter-cloudflare-workersを使用する理由がない限り、代わりにadapter-cloudflareを使用することをお勧めします。両方のアダプターは同等の機能を持っていますが、Cloudflare Pagesは自動ビルドとデプロイを伴うGitHub連携、プレビューデプロイメント、即時ロールバックなどの機能を提供しています。

使用方法

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

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

export default {
	kit: {
		adapter: adapter({
			config: 'wrangler.toml',
			platformProxy: {
				configPath: 'wrangler.toml',
				environment: undefined,
				experimentalJsonConfig: false,
				persist: false
			}
		})
	}
};

オプション

config

カスタムのwrangler.toml設定ファイルへのパスを指定します。

platformProxy

ローカルバインディングでエミュレートされるplatform.envの設定を指定します。利用可能なオプションの完全なリストについては、WranglerのAPIドキュメントのgetPlatformProxyセクションを参照してください。

基本設定

このアダプターは、プロジェクトルートに wrangler.toml ファイルがあることを期待します。次のようになります。

// wrangler.toml
name = "<your-service-name>"
account_id = "<your-account-id>"

main = "./.cloudflare/worker.js"
site.bucket = "./.cloudflare/public"

build.command = "npm run build"

compatibility_date = "2021-11-12"
workers_dev = true

<your-service-name> は何でも構いません。<your-account-id> は、Cloudflare ダッシュボードにログインして URL の末尾から取得することで見つけることができます。

https://dash.cloudflare.com/<your-account-id>

.cloudflare ディレクトリ (または main および site.bucket に指定したディレクトリ) を .gitignore に追加する必要があります。

まだ準備できていない場合は、wrangler をインストールしてログインする必要があります。

npm i -g wrangler
wrangler login

次に、アプリをビルドしてデプロイします。

wrangler deploy

カスタム設定

wrangler.toml 以外の設定ファイルを使用する場合は、config オプションを使用して指定できます。

Node.js 互換性を有効にする場合は、wrangler.toml に「nodejs_compat」フラグを追加できます。

// wrangler.toml
compatibility_flags = [ "nodejs_compat" ]

ランタイム API

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 devコマンドを実行してください。

解説：

開発環境のエミュレーション：

開発中やプレビュー時に、Cloudflare Workers環境を模倣します。
これにより、実際のCloudflare環境がなくても、ローカルで開発やテストが可能になります。

wrangler.tomlの重要性：

このファイルにある設定に基づいて、ローカルバインディングが作成されます。
これらのバインディングはplatform.envを通じて、開発中のアプリケーションに環境変数などを提供します。

platformProxyオプション：

アダプター設定の中にあるこのオプションを使用して、ローカルバインディングの動作をカスタマイズできます。

wranglerバージョン3の使用：

ビルドのテストには特にwranglerのバージョン3を使用することが推奨されています。
これは、このバージョンが特定の機能や安定性を提供しているためと考えられます。

wrangler devコマンド：

サイトをビルドした後、このコマンドを使用して開発サーバーを起動します。
これにより、ローカル環境でアプリケーションをテストし、開発を進めることができます。

これらの設定と手順は、Cloudflare Workersを使用したプロジェクトの開発とテストを効率的に行うために重要です。特に、ローカル環境でCloudflareの機能を正確にエミュレートすることで、本番環境でのトラブルを事前に防ぐことができます。

トラブルシューティング

Workerのサイズ制限

Workersにデプロイする際、SvelteKitによって生成されたサーバーは単一のファイルにバンドルされます。圧縮後のサイズが制限を超えると、Wranglerはあなたのワーカーの公開に失敗します。通常はこの制限に達することはありませんが、一部の大きなライブラリがこの問題を引き起こす可能性があります。その場合、クライアントサイドでのみそのようなライブラリをインポートすることで、ワーカーのサイズを減らすことができます。詳細については、FAQをご覧ください。

解説：

Cloudflare Workersにはファイルサイズの制限があります。
SvelteKitのサーバーコードは単一ファイルにバンドルされます。
大きなライブラリを使用すると、この制限を超える可能性があります。
解決策として、大きなライブラリはクライアントサイドでのみ使用することを検討してください。

ファイルシステムへのアクセス

Cloudflare Workersではfs（ファイルシステム）を使用できません。該当するルートを事前にレンダリングする必要があります。

解説：

Cloudflare Workersは、セキュリティとパフォーマンスの理由から、直接ファイルシステムにアクセスすることができません。
ファイルシステムへのアクセスが必要なルートがある場合、それらを事前レンダリング（プリレンダリング）する必要があります。
プリレンダリングとは、ビルド時にページを生成し、静的なHTMLとしてサーブすることを意味します。

これらのトラブルシューティング項目は、Cloudflare Workersを使用してSvelteKitアプリケーションをデプロイする際に遭遇する可能性のある一般的な問題に対処するためのものです。サイズ制限やファイルシステムの制約を理解し、適切に対応することで、スムーズなデプロイメントと効率的な運用が可能になります。