Svelte入門：リファレンス Configuration -Vol.19-

よっしー

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

今日は、SvelteKitのリファレンスについて解説しています。

背景
KitConfig
1. version
おわりに

背景

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

KitConfig

kit プロパティは SvelteKit を設定するために使用され、以下のようなプロパティを持つことができます：

svelte.config.js ファイル内の kit オブジェクトは、SvelteKit アプリケーションの核となる設定を定義します。このプロパティによって、アプリケーションのルーティング、ビルド、デプロイなどの多くの側面をカスタマイズできます。

例えば：

const config = {
  kit: {
    // KitConfig プロパティがここに入ります
    adapter: adapter(),
    paths: {
      base: '/my-app',
      assets: 'https://cdn.example.com'
    },
    // その他の設定...
  }
};

KitConfig には多くのプロパティが含まれる可能性があり、プロジェクトの要件に応じて以下のような設定が可能です：

adapter: アプリケーションのデプロイ先環境を定義します（Node.js、静的サイト、AWS Lambda など）
paths: ベースパスやアセットパスなどのパス設定
prerender: プリレンダリングの設定
env: 環境変数の扱い方
csp: コンテンツセキュリティポリシー設定
alias: インポートパスのエイリアス
files: さまざまなファイルやディレクトリの場所
outDir: ビルド出力先のディレクトリ
version: アプリケーションのバージョン管理方法

こうした設定を変更することで、SvelteKit アプリケーションの動作を特定の要件に合わせてカスタマイズできます。

（注：具体的な各プロパティの詳細説明がドキュメントにはさらに記載されていると思われますが、入力された文章には含まれていないため、一般的な説明に留めています。）

version

SvelteKitのバージョン管理に関する設定です。

クライアントサイドナビゲーションは、ユーザーがアプリを使用している間に新しいバージョンをデプロイすると問題が発生する可能性があります。新しいページのコードが既に読み込まれている場合、古いコンテンツが表示される可能性があります。また、読み込まれていない場合、アプリのルートマニフェストが既に存在しないJavaScriptファイルを指している可能性があります。

SvelteKitはバージョン管理を通じてこの問題の解決を支援します。ページの読み込み中にエラーが発生し、新しいバージョンがデプロイされたことが検出された場合（ここで指定されたnameを使用。デフォルトではビルドのタイムスタンプ）、従来の完全ページナビゲーションにフォールバックします。ただし、次のページのJavaScriptが既に読み込まれている場合など、すべてのナビゲーションがエラーになるわけではありません。このような場合にも完全ページナビゲーションを強制したい場合は、pollIntervalを設定し、beforeNavigateを使用するような技術を利用します。

name

現在のアプリバージョン文字列です。指定する場合、これは決定論的でなければなりません（例：Math.random()やDate.now().toString()ではなくコミット参照）。指定しない場合、デフォルトではビルドのタイムスタンプが使用されます。

例えば、現在のコミットハッシュを使用するには、git rev-parse HEADを使用できます：

// svelte.config.js
import * as child_process from 'node:child_process';

export default {
	kit: {
		version: {
			name: child_process.execSync('git rev-parse HEAD').toString().trim()
		}
	}
};

pollInterval

デフォルト値: 0

バージョン変更をポーリングする間隔（ミリ秒）です。この値が0の場合、ポーリングは行われません。

実装例：バージョン変更検出時に完全ページナビゲーションを強制する

<!-- +layout.svelte -->
<script>
	import { beforeNavigate } from '$app/navigation';
	import { updated } from '$app/state';

	beforeNavigate(({ willUnload, to }) => {
		if (updated.current && !willUnload && to?.url) {
			location.href = to.url.href;
		}
	});
</script>

pollIntervalを0以外の値に設定すると、SvelteKitはバックグラウンドで新しいバージョンをポーリングし、検出するとupdated.currentの値をtrueに設定します。

バージョン管理が重要な理由

SPAやクライアントサイドルーティングを使用するアプリでは、長時間セッションの間にデプロイが行われると、次のような問題が発生する可能性があります：

古いコードと新しいデータの不一致: ブラウザに古いJSがあるのに新しいAPIにアクセスするケース
存在しないアセットへの参照: デプロイで削除されたJSファイルを読み込もうとする場合
ルートマニフェストの不整合: クライアントのルートマップが新しいサーバー側の構造と合わない場合

CI/CDパイプラインでの自動バージョニング

// svelte.config.js
export default {
	kit: {
		version: {
			name: process.env.BUILD_ID || process.env.COMMIT_SHA || new Date().toISOString(),
			pollInterval: 60000 // 1分ごとに新バージョンをチェック
		}
	}
};

バージョン変更を検出してユーザーに通知

<!-- +layout.svelte -->
<script>
	import { updated } from '$app/state';
	
	// アプリの更新をチェック
	$: if ($updated.current) {
		// 更新が利用可能
	}
</script>

{#if $updated.current}
	<div class="update-banner">
		新しいバージョンが利用可能です。
		<button on:click={() => location.reload()}>
			今すぐ更新
		</button>
	</div>
{/if}

ビルドタイムスタンプとビルド環境の表示

// svelte.config.js
export default {
	kit: {
		version: {
			name: `${process.env.NODE_ENV}-${new Date().toISOString()}`,
			pollInterval: process.env.NODE_ENV === 'production' ? 300000 : 0 // 本番環境でのみポーリング
		}
	}
};

バージョン管理機能を適切に設定することで、ユーザー体験を損なうことなく継続的デプロイメントを実現できます。特に、長時間利用される可能性のあるアプリケーションでは、この機能は非常に重要になります。