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

背景

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

@sveltejs/kit

PrerenderHttpErrorHandler

interface PrerenderHttpErrorHandler {…}

(details: {
status: number;
path: string;
referrer: string | null;
referenceType: 'linked' | 'fetched';
message: string;
}): void;

解説

PrerenderHttpErrorHandlerは、SvelteKitのプリレンダリング処理中にHTTPエラーが発生した場合に呼び出されるハンドラー関数のインターフェースです。このハンドラーは、静的サイト生成（SSG）中に発生するHTTPエラーをカスタム処理するために使用されます。

パラメータの詳細

ハンドラー関数は以下のプロパティを持つオブジェクトを受け取ります：

1. status: HTTP ステータスコード
   • エラーの種類を示す数値（例：404、500など）
2. path: エラーが発生したパス
   • プリレンダリング中にエラーが発生したURL/パス
3. referrer: 参照元
   • このパスを参照していたページのパス（存在する場合）
   • リンクが存在しない場合は null
4. referenceType: 参照の種類
   • 'linked': HTMLリンク（<a href>）から参照されていた場合
   • 'fetched': fetchリクエストで取得しようとしていた場合
5. message: エラーの詳細メッセージ
   • エラーの原因や追加情報を説明するテキスト

使用例

SvelteKitの設定ファイルでこのインターフェースを実装する例：

// svelte.config.js
export default {
  kit: {
    prerender: {
      handleHttpError: (details) => {
        // 404エラーは許容する（ログは残す）
        if (details.status === 404) {
          console.warn(`🟡 404エラーを無視します: ${details.path} (参照元: ${details.referrer || 'なし'})`);
          return;
        }
        
        // 特定のAPIエンドポイントでのエラーは無視
        if (details.path.startsWith('/api/legacy/') && details.status === 500) {
          console.warn(`🟠 レガシーAPIエラーを無視: ${details.path}`);
          return;
        }
        
        // それ以外のエラーはビルドを失敗させる
        throw new Error(
          `🔴 プリレンダリングエラー ${details.status} at ${details.path}\n` +
          `   メッセージ: ${details.message}\n` +
          `   参照元: ${details.referrer || 'なし'} (${details.referenceType})`
        );
      }
    }
  }
};

実践的なユースケース

このハンドラーは以下のようなシナリオで特に役立ちます：

1. 一部の404を許容する:
   • 外部APIやリソースがまだ存在しない場合でも、ビルドを継続できるようにする
2. エラーのカスタムログ記録:
   • ビルドログとは別にエラーを特定のフォーマットや場所に記録
3. 条件付きビルド中断:
   • 特定のクリティカルなページでのエラーのみビルドを中断させる
4. デバッグ情報の収集:
   • エラーパターンを分析して、サイト構造の問題を特定するためのデータ収集

SvelteKitのプリレンダリングはウェブサイト全体を静的ファイルとして生成するため、このハンドラーはデプロイ前にサイト内の問題を発見して対処するための重要なツールとなります。

PrerenderHttpErrorHandlerValue

type PrerenderHttpErrorHandlerValue =
	| 'fail'
	| 'warn'
	| 'ignore'
	| PrerenderHttpErrorHandler;

解説

PrerenderHttpErrorHandlerValueは、SvelteKitのプリレンダリング処理中にHTTPエラーが発生した場合の対応方法を指定するための型定義です。この型は、3種類の文字列リテラルのいずれかまたはカスタムハンドラー関数を値として受け付けます。

選択可能な値

1. 'fail':
   • HTTPエラーが発生した場合にプリレンダリングプロセスを即座に中断し、ビルドを失敗させます
   • 全てのリンクやエンドポイントが正常に動作することを保証したい場合に適しています
   • これがデフォルトの動作です
2. 'warn':
   • HTTPエラーが発生しても、コンソールに警告を表示するだけでビルドプロセスは継続します
   • 問題を把握しつつも、必ずしも修正が必要ではない場合に有用です
3. 'ignore':
   • HTTPエラーを完全に無視し、何の通知もせずにビルドを続行します
   • 特定のエラーが予期されており、処理の必要がない場合に使用します
4. PrerenderHttpErrorHandler:
   • カスタムハンドラー関数を指定して、エラーの詳細に基づいて個別に対応できます
   • 特定のステータスコードやパスパターンごとに異なる対応をしたい場合に最も柔軟な選択肢です

使用例

SvelteKitの設定ファイルでの典型的な使用例：

// svelte.config.js
export default {
  kit: {
    prerender: {
      // 基本的な使用法：文字列リテラルを指定
      handleHttpError: 'warn',
      
      // 高度な使用法：カスタムハンドラー関数
      // handleHttpError: (details) => {
      //   // 404エラーは許容
      //   if (details.status === 404) {
      //     console.log(`ページが見つかりません: ${details.path}`);
      //     return;
      //   }
      //   
      //   // その他のエラーはビルドを失敗させる
      //   throw new Error(`${details.status} エラー: ${details.path}`);
      // }
    }
  }
};

実践的な適用シナリオ

この設定の選択は、プロジェクトのニーズによって異なります：

1. 初期開発段階:
   • 'warn'を使用して、全ての問題を把握しつつも開発を継続できるようにする
2. 本番デプロイ前:
   • 'fail'または厳格なカスタムハンドラーを使用して、すべての問題が解決されていることを確認
3. 部分的なプリレンダリング:
   • カスタムハンドラーを使用して、メインコンテンツのエラーのみを厳格に扱い、補助的なコンテンツのエラーは許容する
4. 外部依存APIとの統合:
   • 開発中のAPIエンドポイントに関連するエラーを一時的に無視するため、特定パスのみignore相当の処理を行う

この型システムにより、SvelteKitはプリレンダリングプロセスの厳格さを柔軟に設定できるようになり、様々な開発ワークフローやデプロイシナリオに対応できます。

PrerenderMap

type PrerenderMap = Map<string, PrerenderOption>;

解説

PrerenderMapは、SvelteKitのプリレンダリング設定を保存するための型定義です。これは、JavaScriptの標準的なMapオブジェクトを使用して、URLパス（文字列）とそれに対応するプリレンダリングオプション（PrerenderOption）を関連付けるデータ構造を表します。

構造の詳細

• キー（string）: プリレンダリングするURLパス（例：/blog、/aboutなど）
• 値（PrerenderOption）: そのパスに適用されるプリレンダリングの設定オプション

使用目的

この型は、SvelteKitのアプリケーション内で様々なルートに対して異なるプリレンダリング設定を適用するために使用されます。これにより、開発者はアプリケーション内の特定のページやルートに対して、カスタマイズされたプリレンダリング動作を指定できます。

例えば、一部のページは完全に静的にプリレンダリングし、他のページは動的なクエリパラメータを持つパスを生成するよう設定することができます。

実装例

以下はPrerenderMapを使用する例です：

// +routes.ts や hooks.server.ts などで使用される例
import type { PrerenderMap } from '@sveltejs/kit';

export function getPrerenderRoutes(): PrerenderMap {
  const prerenderMap = new Map();
  
  // 基本的なページをプリレンダリング
  prerenderMap.set('/', { prerender: true });
  prerenderMap.set('/about', { prerender: true });
  
  // ブログページには特別な設定を適用
  prerenderMap.set('/blog', { 
    prerender: true,
    // ここに追加のオプションがあれば設定
  });
  
  // ダイナミックルートのプリレンダリング設定
  prerenderMap.set('/products/[id]', {
    prerender: true,
    entries: [
      { id: '1' },
      { id: '2' },
      { id: '3' }
    ]
  });
  
  return prerenderMap;
}

関連する型と機能

PrerenderMapは一般的に以下のSvelteKit機能と一緒に使用されます：

1. プリレンダリング設定: svelte.config.jsで全体的なプリレンダリング設定を行う
2. 動的なプリレンダリング判断: ルート単位でプリレンダリングするかどうかを決定
3. エントリーポイント生成: 動的ルートに対して、どのパラメータの組み合わせをプリレンダリングするか指定

PrerenderOption型の詳細によりますが、通常は少なくともprerender: booleanプロパティを含み、必要に応じて追加のオプションやエントリーリストを含むことができます。

この型を使用することで、SvelteKitアプリケーション内の様々なルートに対するプリレンダリング戦略を柔軟に構成できます。

おわりに

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