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

よっしー

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

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

背景
@sveltejs/kit
おわりに

背景

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

@sveltejs/kit

PrerenderMissingIdHandler

interface PrerenderMissingIdHandler {…}

(details: { path: string; id: string; referrers: string[]; message: string }): void;

解説

PrerenderMissingIdHandlerは、SvelteKitのプリレンダリング処理中に「見つからないID」の問題が発生した場合に呼び出されるハンドラー関数のインターフェースです。

この問題は、プリレンダリング中に存在しないページやルートへのリンクが検出された場合に発生します。例えば、動的ルート（[id]や[slug]などのパラメータを含むルート）が正しく定義されていないか、必要なエントリーが提供されていない場合などです。

パラメータの詳細

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

path: 問題が検出されたパス
- 存在しないと判断されたURL/パス
id: 見つからないルートID
- SvelteKitの内部で使用されるルート識別子
- 例えば「/blog/[slug]」のような形式
referrers: 参照元のリスト
- このパスを参照しているページのパスの配列
- どのページから問題のリンクが参照されているかを特定するのに役立つ
message: エラーの詳細メッセージ
- 問題の説明を含む文字列

使用例

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

// svelte.config.js
export default {
  kit: {
    prerender: {
      handleMissingId: (details) => {
        // 特定のパスパターンのエラーは無視
        if (details.path.startsWith('/api/')) {
          console.warn(`APIへのリンクはプリレンダリングされません: ${details.path}`);
          return;
        }
        
        // 詳細なログを出力
        console.error(`見つからないルートID: ${details.id}`);
        console.error(`問題のパス: ${details.path}`);
        console.error(`参照元ページ:`);
        details.referrers.forEach(referrer => {
          console.error(` - ${referrer}`);
        });
        console.error(`メッセージ: ${details.message}`);
        
        // ビルドを失敗させる
        throw new Error(`プリレンダリングエラー: 見つからないルートID "${details.id}"`);
      }
    }
  }
};

実践的なユースケース

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

動的ルートのエントリー検証:
- 動的パラメータを持つルート（/blog/[slug]など）に対して、必要なすべてのスラグ値が提供されているか確認
壊れたリンクの検出:
- サイト内の壊れたリンクを見つけて、どのページから参照されているかを特定
条件付きコンテンツの対応:
- 一部のコンテンツが特定の条件でのみ存在する場合（例：公開ステータスに基づく）、その状況を適切に処理
リンクミスの分析:
- 開発中に意図しないリンクのパターンを特定し、構造的な問題を解決

このハンドラーを適切に実装することで、静的サイト生成時の問題を早期に発見し、本番環境にデプロイする前に修正することができます。

PrerenderMissingIdHandlerValue

type PrerenderMissingIdHandlerValue =
	| 'fail'
	| 'warn'
	| 'ignore'
	| PrerenderMissingIdHandler;

解説

PrerenderMissingIdHandlerValueは、SvelteKitのプリレンダリング処理中に「見つからないID」の問題が発生した場合の対応方法を指定するための型定義です。この型は、定義済みの3つの文字列リテラルのいずれか、またはカスタムハンドラー関数を値として受け付けます。

選択可能な値

'fail':
- 見つからないIDが検出された場合にプリレンダリングプロセスを即座に中断し、ビルドを失敗させます
- すべてのリンクが有効であることを保証したい場合に適しています
- 一般的に本番環境向けビルドで使用されます
'warn':
- 見つからないIDが検出されても、コンソールに警告を表示するだけでビルドプロセスは継続します
- 問題を認識しつつも、ビルドを完了させたい開発段階で有用です
'ignore':
- 見つからないIDを完全に無視し、何の通知もせずにビルドを続行します
- 特定の状況下で意図的に「存在しない」リンクを含める場合に使用します
PrerenderMissingIdHandler:
- カスタムハンドラー関数を指定して、問題の詳細に基づいて個別に対応できます
- 特定のパスパターンに対してのみ警告や失敗を適用したい場合に最も柔軟です

使用例

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

// svelte.config.js
export default {
  kit: {
    prerender: {
      // 基本的な使用法：定義済みの文字列値
      handleMissingId: 'warn',
      
      // 高度な使用法：カスタムハンドラー
      // handleMissingId: (details) => {
      //   // APIパスは無視
      //   if (details.path.startsWith('/api/')) {
      //     return;
      //   }
      //   
      //   // ユーザーページの問題は警告のみ
      //   if (details.path.startsWith('/users/')) {
      //     console.warn(`ユーザーページが見つかりません: ${details.path}`);
      //     console.warn(`参照元: ${details.referrers.join(', ')}`);
      //     return;
      //   }
      //   
      //   // その他の問題はビルド失敗
      //   throw new Error(`存在しないページへのリンク: ${details.path}`);
      // }
    }
  }
};

実践的な適用シナリオ

この設定値の選択は、プロジェクトの状況や要件によって異なります：

開発モード:
- 'warn'を使用して、問題を把握しながらも開発を継続できるようにする
CI/CDパイプライン:
- 'fail'を使用して、壊れたリンクが本番環境に入り込まないようにする
特殊なコンテンツ管理:
- カスタムハンドラーを使用して、条件付きで表示されるコンテンツへのリンクを適切に処理する
- 例えば、公開済みの記事のみプリレンダリングするが、下書き記事へのリンクは警告のみにするなど
フェーズド開発:
- 開発中の新機能に関連するリンクは一時的に許容するが、既存機能のリンクエラーは厳格に処理する

この型を使用することで、SvelteKitアプリケーションのプリレンダリングプロセスをプロジェクトの現在のフェーズやニーズに合わせて調整することができます。

PrerenderOption

type PrerenderOption = boolean | 'auto';

解説

PrerenderOptionは、SvelteKitフレームワークにおいてプリレンダリングの動作を制御するための型定義です。この型は、各ルートのプリレンダリングをどのように処理するかを指定するために使用されます。

取り得る値

この型は以下の値のいずれかを取ることができます：

true:
- 指定されたルートを必ずプリレンダリングします
- 静的に生成されるHTMLファイルとして出力されます
- サーバーサイドの処理なしに配信できるようになります
false:
- 指定されたルートをプリレンダリングしません
- このルートへのリクエストは常にサーバーサイドでレンダリングされます（SSR）
- 動的なデータや認証が必要なページに適しています
'auto':
- ルートの性質に基づいて自動的に決定します
- ロード関数がサーバー依存のAPIを使用していない場合はプリレンダリングされます
- ルートがローカルファイルシステムや環境変数のみにアクセスする場合は、プリレンダリングされる可能性があります

ルートレベルでの使用

各ルートのモジュールでexport const prerenderを使用して設定できます：

// +page.js/+page.ts または +layout.js/+layout.ts
export const prerender = true; // このページを必ずプリレンダリング

または：

// +page.js/+page.ts または +layout.js/+layout.ts
export const prerender = false; // このページをプリレンダリングしない

または：

// +page.js/+page.ts または +layout.js/+layout.ts
export const prerender = 'auto'; // ルートの性質に基づいて自動判断

グローバルレベルでの使用

アプリケーション全体のデフォルト設定としてsvelte.config.jsで指定することもできます：

// svelte.config.js
export default {
  kit: {
    prerender: {
      default: true // すべてのルートをデフォルトでプリレンダリング
      // または
      // default: false // デフォルトではプリレンダリングしない
      // または
      // default: 'auto' // 自動判断（デフォルト値）
    }
  }
};