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

よっしー

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

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

背景

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

@sveltejs/kit

CspDirectives

interface CspDirectives {…}

'child-src'?: Csp.Sources;

'default-src'?: Array<Csp.Source | Csp.ActionSource>;

'frame-src'?: Csp.Sources;

'worker-src'?: Csp.Sources;

'connect-src'?: Csp.Sources;

'font-src'?: Csp.Sources;

'img-src'?: Csp.Sources;

'manifest-src'?: Csp.Sources;

'media-src'?: Csp.Sources;

'object-src'?: Csp.Sources;

'prefetch-src'?: Csp.Sources;

'script-src'?: Array<Csp.Source | Csp.ActionSource>;

'script-src-elem'?: Csp.Sources;

'script-src-attr'?: Csp.Sources;

'style-src'?: Array<Csp.Source | Csp.ActionSource>;

'style-src-elem'?: Csp.Sources;

'style-src-attr'?: Csp.Sources;

'base-uri'?: Array<Csp.Source | Csp.ActionSource>;

sandbox?: Array
| 'allow-downloads-without-user-activation'
| 'allow-forms'
| 'allow-modals'
| 'allow-orientation-lock'
| 'allow-pointer-lock'
| 'allow-popups'
| 'allow-popups-to-escape-sandbox'
| 'allow-presentation'
| 'allow-same-origin'
| 'allow-scripts'
| 'allow-storage-access-by-user-activation'
| 'allow-top-navigation'
| 'allow-top-navigation-by-user-activation'
>;

'form-action'?: Array<Csp.Source | Csp.ActionSource>;

'frame-ancestors'?: Array<Csp.HostSource | Csp.SchemeSource | Csp.FrameSource>;

'navigate-to'?: Array<Csp.Source | Csp.ActionSource>;

'report-uri'?: string[];

'report-to'?: string[];

'require-trusted-types-for'?: Array<'script'>;

'trusted-types'?: Array<'none' | 'allow-duplicates' | '*' | string>;

'upgrade-insecure-requests'?: boolean;

'require-sri-for'?: Array<'script' | 'style' | 'script style'>;

非推奨

'block-all-mixed-content'?: boolean;

非推奨

'plugin-types'?: Array<`${string}/${string}` | 'none'>;

非推奨

referrer?: Array
| 'no-referrer'
| 'no-referrer-when-downgrade'
| 'origin'
| 'origin-when-cross-origin'
| 'same-origin'
| 'strict-origin'
| 'strict-origin-when-cross-origin'
| 'unsafe-url'
| 'none'
>;

非推奨

解説

CspDirectivesインターフェースは、SvelteKitアプリケーションでContent Security Policy（CSP）を設定するための包括的な型定義を提供します。CSPはWebセキュリティの重要な要素で、さまざまな種類のコンテンツやリソースについて、どのソースから読み込みや実行を許可するかを細かく制御できます。

リソースの読み込み制御

default-src: 他のディレクティブが指定されていない場合のフォールバック
script-src: JavaScriptの読み込みと実行を制御
style-src: CSSスタイルシートの読み込みを制御
img-src: 画像の読み込みを制御
connect-src: XHR、WebSocketなどの接続先を制御
font-src: Webフォントの読み込み元を制御
media-src: オーディオ、ビデオの読み込み元を制御
frame-src: iframe内のコンテンツの読み込み元を制御
worker-src: Service WorkerやWeb Workerのスクリプト元を制御
manifest-src: マニフェストファイルの読み込み元を制御
object-src: <object>、<embed>、<applet>タグの読み込み元を制御

より詳細なスクリプト・スタイル制御

script-src-elem: スクリプト要素の読み込み元を制御
script-src-attr: インラインスクリプト属性を制御
style-src-elem: スタイル要素の読み込み元を制御
style-src-attr: インラインスタイル属性を制御

ナビゲーションと構造制御

base-uri: ベースURLを制御（<base>タグ）
form-action: フォーム送信先を制御
frame-ancestors: どのページがアプリをiframeに埋め込めるかを制御
navigate-to: リダイレクト・フォーム送信先を制御

サンドボックス制御

sandbox: iframe内のコンテンツに対する制限を設定
- 様々な許可を個別に設定可能（フォーム送信、ポップアップ、スクリプト実行など）

Web信頼性・セキュリティ強化

upgrade-insecure-requests: HTTP接続をHTTPSに自動的にアップグレード
require-trusted-types-for: Trusted TypesによるDOM XSSの防止
trusted-types: 許可されるTrusted Typesポリシーを指定
require-sri-for: Subresource Integrityチェックを強制

レポート設定

report-uri: ポリシー違反のレポート先URL（非推奨、report-toを使用推奨）
report-to: ポリシー違反のレポート先グループ名

非推奨ディレクティブ

block-all-mixed-content: 混合コンテンツのブロック（HTTPS上でのHTTPリソース）
plugin-types: 許可するプラグインタイプを制限
referrer: リファラーポリシーを指定

実装例

SvelteKitでCSPを適用する例：

// hooks.server.ts
import type { Handle } from '@sveltejs/kit';
import type { CspDirectives } from '@sveltejs/kit';

export const handle: Handle = async ({ event, resolve }) => {
  const csp: CspDirectives = {
    'default-src': ['self'],
    'script-src': ['self', 'https://trusted-analytics.com'],
    'style-src': ['self', 'unsafe-inline'],
    'img-src': ['self', 'data:', 'https://images.example.com'],
    'connect-src': ['self', 'https://api.example.com'],
    'frame-ancestors': ['none'],  // clickjacking防止
    'upgrade-insecure-requests': true
  };

  // CSPヘッダーをレスポンスに追加
  const response = await resolve(event, {
    transformPageChunk: ({ html }) => html
  });
  
  // CSPヘッダーを生成して設定
  const cspString = Object.entries(csp)
    .map(([key, values]) => {
      if (typeof values === 'boolean') {
        return values ? key : '';
      }
      return `${key} ${values.join(' ')}`;
    })
    .filter(Boolean)
    .join('; ');
  
  response.headers.set('Content-Security-Policy', cspString);
  return response;
};

この型システムにより、CSPの設定が間違っていないことを型チェックで確認でき、開発者はより安全なWebアプリケーションを構築できます。

HttpMethod

type HttpMethod =
	| 'GET'
	| 'HEAD'
	| 'POST'
	| 'PUT'
	| 'DELETE'
	| 'PATCH'
	| 'OPTIONS';

解説

HttpMethodは、HTTP通信で使用される標準的なHTTPメソッドを表す型定義です。これはSvelteKitフレームワーク内でHTTPリクエストのメソッドを型安全に扱うために使用されます。

この型に含まれる各HTTPメソッドの意味と用途は以下の通りです：

GET: リソースの取得に使用されます。サーバーに対してデータの読み取りのみを行い、状態を変更しません。
HEAD: GETと同様ですが、レスポンスボディを含まず、ヘッダー情報のみを返します。リソースのメタデータだけを取得したい場合に使用します。
POST: 新しいリソースの作成やデータの送信に使用されます。フォーム送信やAPIへのデータ提出などに一般的に使われます。
PUT: 指定したURIにリソースを作成または置換するために使用されます。既存のリソースを完全に置き換えます。
DELETE: 指定したリソースの削除に使用されます。
PATCH: リソースの部分的な修正に使用されます。PUTが完全な置換を行うのに対し、PATCHは一部のフィールドだけを更新します。
OPTIONS: サーバーがサポートしているメソッドや、クロスオリジンリクエストの前に行われるプリフライトリクエストに使用されます。

SvelteKitでは、この型はルートのハンドラー関数やAPI定義において、どのHTTPメソッドがサポートされているかを明示するために使用されます。例えば：

// +server.ts
export function GET() {
  // GETリクエストの処理
}

export function POST() {
  // POSTリクエストの処理
}

この型定義により、開発者はサポートされていないHTTPメソッドを誤って使用することがなくなり、型安全性が向上します。

Logger

interface Logger {…}

(msg: string): void;

success(msg: string): void;

error(msg: string): void;

warn(msg: string): void;

minor(msg: string): void;

info(msg: string): void;

解説

Loggerインターフェースは、SvelteKitフレームワーク内でのログ出力を標準化するための型定義です。このインターフェースは、アプリケーションの様々な状況でメッセージを出力するための一貫した方法を提供します。

基本機能

このインターフェースには、以下のメソッドと機能が含まれています：

デフォルトメソッド ((msg: string): void):
- インターフェース自体が関数として呼び出し可能
- 一般的なログメッセージを出力するために使用
メッセージの種類別メソッド:
- success(msg: string): void: 成功メッセージを出力
- error(msg: string): void: エラーメッセージを出力
- warn(msg: string): void: 警告メッセージを出力
- minor(msg: string): void: 重要度の低いメッセージを出力
- info(msg: string): void: 情報メッセージを出力

使用例

SvelteKitでは、主にアプリケーションのビルドプロセス、開発サーバー、またはアダプターなどの内部コンポーネントでこのロガーが使用されます。以下は使用例です：

// ビルドプロセスやアダプター内でのロガー使用例
function build(options: BuildOptions, logger: Logger) {
  logger.info('ビルドを開始します...');
  
  try {
    // ビルドプロセス
    logger('処理中...');
    
    // 成功した場合
    logger.success('ビルドが正常に完了しました');
  } catch (error) {
    // エラーが発生した場合
    logger.error(`ビルド中にエラーが発生しました: ${error.message}`);
  }
  
  // 警告が必要な場合
  if (someWarningCondition) {
    logger.warn('非推奨のオプションが使用されています');
  }
  
  // 補足情報
  logger.minor('最適化のヒント: パフォーマンス向上のためにキャッシュを有効にしてください');
}

実装の背景

このインターフェースの設計は、異なるログレベルを区別して表示する必要性から来ています。これにより：

重大度に基づいて視覚的に区別（色分けなど）できる
フィルタリングが可能（例：開発時には全てのログを表示し、本番環境ではエラーのみ表示）
ログ出力の一貫性が確保される

SvelteKitの内部実装では、通常コンソールへの出力をカラー表示するためにライブラリ（例：kleurやchalkなど）と組み合わせて使用されることが多いです。

このようなロガーインターフェースを使用することで、アプリケーションの様々な部分からのログメッセージが一貫した方法で処理され、デバッグや監視が容易になります。

おわりに

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

よっしー

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

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