Svelte入門：リファレンス @sveltejs/kit -Vol.19-

スポンサーリンク
Svelte入門： リファレンス @sveltejs/kit -Vol.19- 用語解説
Svelte入門： リファレンス @sveltejs/kit -Vol.19-
この記事は約10分で読めます。
よっしー
よっしー

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

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

スポンサーリンク

背景

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

@sveltejs/kit

Private types

以下は上記で文書化されている公開型によって参照されていますが、直接インポートすることはできません：

解説

このメッセージは、SvelteKitの型システムについての重要な注意点を伝えています。「プライベート型」とは、SvelteKitのパブリックAPIの一部として参照されているが、ユーザーコードから直接インポートできない型定義を指します。

このような型は通常、以下のような理由でプライベートとして扱われています：

  1. 内部実装の詳細: これらの型はフレームワークの内部実装に関連しており、将来的に変更される可能性があります
  2. 抽象化: エンドユーザーに対して不必要な複雑さを隠すため
  3. 型安全性: 特定の型が間違った方法で使用されることを防ぐため

SvelteKitでは、./$typesから生成された型を使用することが推奨されています。このアプローチにより、SvelteKitはバージョン間の互換性を維持しながら、内部の型定義を自由に変更・改良することができます。

例えば：

  • ServerLoad型は直接インポートするのではなく、./$typesから生成されるPageServerLoadやLayoutServerLoadを使用するべきです
  • 同様に、他の多くの型も./$typesからインポートされる特定の派生型を通じてアクセスするべきです

これは、SvelteKitのAPIの安定性を長期的に確保するための設計上の決定です。

AdapterEntry

interface AdapterEntry {…}

id: string;

HTTP サービス（例：サーバーレス関数）を一意に識別する文字列で、重複排除に使用されます。例えば、/foo/a-[b] と /foo/[c] は異なるルートですが、Netlify の _redirects ファイルでは両方とも /foo/:param として表現されるため、同じ ID を共有します。

filter(route: RouteDefinition): boolean;

候補ルートを現在のルートと比較して、現在のルートとグループ化するべきかどうかを判断する関数です。 ユースケース：

  • フォールバックページ: /foo/[c] は /foo/a-[b] のフォールバックであり、/[...catchall] はすべてのルートのフォールバックです
  • 共通の config を共有するルートのグループ化: /foo はエッジにデプロイされるべきで、/bar と /baz はサーバーレス関数にデプロイされるべきです
complete(entry: { generateManifest(opts: { relativePath: string }): string }): MaybePromise<void>;

エントリが作成された後に呼び出される関数です。ここで関数をファイルシステムに書き込み、リダイレクトマニフェストを生成する必要があります。

解説

AdapterEntryインターフェースは、SvelteKitのアダプターシステム内で重要な役割を果たします。このインターフェースは、ルートをどのようにデプロイ対象（例：サーバーレス関数、エッジ関数など）にマッピングするかを定義します。

id: string
  • これはHTTPサービスを一意に識別する文字列です
  • 特に重要なのは、異なるSvelteKitルートが同じデプロイ対象にマップされる可能性があることです
  • 例：動的パラメータを持つ複数のルート（/user/[id]と/profile/[name]）は、サーバーレス環境では同じ関数として処理される場合があります
filter(route: RouteDefinition): boolean
  • このメソッドは、特定のルートがこのエントリに含まれるべきかどうかを判断します
  • 主に2つの用途があります：
    1. フォールバックの処理: より具体的なルートがマッチしない場合に使用される汎用ルートを定義します
    2. デプロイ設定に基づくグループ化: 特定のデプロイ環境（エッジ、サーバーレス関数など）に向けて設計されたルートをグループ化します
complete(entry: {...}): MaybePromise<void>
  • エントリーの処理が完了した後に呼び出されるメソッドです
  • 主な責務は：
    • 関数コードをファイルシステムに書き込む
    • リダイレクトマニフェスト（ルーティングルール）を生成する
    • 必要に応じて設定ファイルを更新する
実践的な使用例

例えば、Netlifyアダプターを実装する場合：

// Netlifyアダプター実装の一部
function createAdapterEntry(route) {
  return {
    id: convertToNetlifyPath(route.path), // /user/[id] → /user/:id のような変換
    
    filter(otherRoute) {
      // 同じNetlifyパスにマップされるルートをグループ化
      return convertToNetlifyPath(otherRoute.path) === this.id;
    },
    
    async complete(entry) {
      // 1. 関数コードをファイルに書き込む
      await fs.writeFile(`netlify/functions/${this.id}.js`, generateFunctionCode());
      
      // 2. リダイレクトルールを生成
      const manifest = entry.generateManifest({ relativePath: './' });
      await fs.appendFile('netlify/_redirects', manifest);
    }
  };
}

このインターフェースは、SvelteKitアプリケーションを様々なサーバーレス/JAMstackプラットフォームにデプロイする際の柔軟性を提供し、アダプター開発者がプラットフォーム固有の要件に合わせてルーティングとデプロイロジックをカスタマイズできるようにします。

Csp

namespace Csp {
	type ActionSource = 'strict-dynamic' | 'report-sample';
	type BaseSource =
		| 'self'
		| 'unsafe-eval'
		| 'unsafe-hashes'
		| 'unsafe-inline'
		| 'wasm-unsafe-eval'
		| 'none';
	type CryptoSource =
		`${'nonce' | 'sha256' | 'sha384' | 'sha512'}-${string}`;
	type FrameSource =
		| HostSource
		| SchemeSource
		| 'self'
		| 'none';
	type HostNameScheme = `${string}.${string}` | 'localhost';
	type HostSource =
		`${HostProtocolSchemes}${HostNameScheme}${PortScheme}`;
	type HostProtocolSchemes = `${string}://` | '';
	type HttpDelineator = '/' | '?' | '#' | '\\';
	type PortScheme = `:${number}` | '' | ':*';
	type SchemeSource =
		| 'http:'
		| 'https:'
		| 'data:'
		| 'mediastream:'
		| 'blob:'
		| 'filesystem:';
	type Source =
		| HostSource
		| SchemeSource
		| CryptoSource
		| BaseSource;
	type Sources = Source[];
}

解説

このCsp名前空間は、SvelteKitにおいてContent Security Policy（CSP）を型安全に定義するための型定義を提供しています。CSPはWebアプリケーションのセキュリティを向上させるための重要な仕組みで、どのようなリソースがページ内で読み込まれたり実行されたりできるかを制御します。

ActionSource

特別なCSPディレクティブを指定します：

  • strict-dynamic: 信頼されたスクリプトが動的に他のスクリプトを追加することを許可
  • report-sample: 違反が発生した場合、コードサンプルを含めて報告する
BaseSource

基本的なソース指定子：

  • self: 同一オリジンからのリソースを許可
  • unsafe-eval: evalやFunction構築など動的コード評価を許可
  • unsafe-hashes: インラインスクリプトのハッシュベース許可を有効化
  • unsafe-inline: インラインスクリプトやスタイルを許可
  • wasm-unsafe-eval: WebAssemblyの動的コンパイルを許可
  • none: いかなるソースも許可しない
CryptoSource

暗号学的ハッシュまたはナンスに基づくソース指定：

  • nonce-{ランダム文字列}: 特定のインラインコードに一致するナンス
  • sha256-{ハッシュ}, sha384-{ハッシュ}, sha512-{ハッシュ}: 特定のインラインコードのハッシュ
FrameSource

frame-srcまたはframe-ancestorsディレクティブで使用される型：

  • ホストソース、スキームソース、self、noneのいずれかを指定可能
HostSource

特定のホストを指定するための型：

  • プロトコル（オプショナル）、ホスト名、ポート（オプショナル）を組み合わせた値
  • 例：example.com, https://example.com, example.com:443
SchemeSource

特定のURLスキームを指定するための型：

  • http:, https:, data:, mediastream:, blob:, filesystem:
Source と Sources
  • Source: ホストソース、スキームソース、暗号ソース、基本ソースのいずれか
  • Sources: 複数のソースを配列として表現
実用例

これらの型定義を使用することで、SvelteKitアプリケーションでCSPを設定する際に型安全性が確保されます：

// hooks.server.tsなどでCSPを設定する例
const csp: Record<string, Csp.Sources> = {
  'default-src': ['self'],
  'script-src': ['self', 'https://trusted-cdn.example.com'],
  'style-src': ['self', 'unsafe-inline'],
  'img-src': ['self', 'data:', 'https://images.example.com'],
  'connect-src': ['self', 'https://api.example.com']
};

この型システムにより、CSP設定時の誤字や無効な値を防ぎ、より安全なアプリケーション開発をサポートします。

おわりに

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

よっしー
よっしー

何か質問や相談があれば、コメントをお願いします。また、エンジニア案件の相談にも随時対応していますので、お気軽にお問い合わせください。

それでは、また明日お会いしましょう(^^)

コメント

タイトルとURLをコピーしました