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

よっしー

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

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

背景
@sveltejs/kit
おわりに

背景

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

@sveltejs/kit

MaybePromise

type MaybePromise<T> = T | Promise<T>;

解説

MaybePromise<T>は、SvelteKitフレームワークで使用されるユーティリティ型の一つです。この型は、値が同期的な形式（T型）または非同期的な形式（Promise<T>型）のいずれかで提供される可能性がある場合に使用されます。

意味と使用目的

この型が定義する内容は単純ですが、非常に実用的です：

型Tそのものか、
型Tを解決するPromiseのいずれか

主な使用ケース

SvelteKitでは以下のような場面でよく使用されます：

ロード関数：データの取得が同期的にできる場合もあれば、非同期（APIリクエストなど）を必要とする場合もある
フォーム処理：フォーム送信の処理が即時に完了する場合と、サーバーとの通信が必要な場合の両方をサポート
ミドルウェア・フック：処理が即時または非同期のいずれでも対応できるようにする

実装例

// 同期/非同期の両方をサポートするロード関数の例
export function load(
  { params }
): MaybePromise<{ data: any }> {
  // キャッシュから即座にデータを取得できる場合（同期）
  if (cache.has(params.id)) {
    return { data: cache.get(params.id) };
  }
  
  // そうでなければAPIリクエストが必要（非同期）
  return fetch(`/api/data/${params.id}`)
    .then(r => r.json())
    .then(data => ({ data }));
}

利点

この型が提供する主な利点：

柔軟性: 関数の実装者が状況に応じて同期または非同期で値を返せる自由度を持てる
型安全性: コンパイル時にPromiseか直接の値かを明示的に示すことができる
インターフェースの一貫性: 呼び出し側は常にawaitを使用するか、Promise.then()を使用して結果を処理できる（同期的な値はawaitしても問題ない）

SvelteKitのAPIを使用する際は、この型が頻繁に使われているため、返り値が同期的か非同期的かを柔軟に扱えるようになっています。

PrerenderEntryGeneratorMismatchHandler

interface PrerenderEntryGeneratorMismatchHandler {…}

(details: { generatedFromId: string; entry: string; matchedId: string; message: string }): void;

解説

PrerenderEntryGeneratorMismatchHandlerは、SvelteKitのプリレンダリング処理中に発生する特定の不一致（ミスマッチ）を処理するためのインターフェースです。

このインターフェースは、プリレンダリング中に生成されたエントリー（通常はURL）が想定と異なるルートにマッチした場合に呼び出されるハンドラー関数を定義しています。

パラメータの詳細

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

generatedFromId: 元のエントリーを生成したルートのID
- これは通常、プリレンダリングエントリーを生成したSvelteKitのルートファイル（例：/routes/blog/[slug]/+page.svelte）を参照します
entry: 生成されたエントリー（通常はURL）
- プリレンダリングする予定のパス（例：/blog/hello-world）
matchedId: 実際にエントリーがマッチしたルートのID
- 生成されたエントリーが意図したルートではなく別のルートにマッチした場合に設定されます
message: 不一致の詳細を説明するメッセージ
- 通常は問題の診断に役立つ説明が含まれます

使用例

このインターフェースは主に、SvelteKitのプリレンダリング設定内でミスマッチが検出された場合の動作をカスタマイズするために使用されます：

// svelte.config.js
export default {
  kit: {
    prerender: {
      handleEntryGeneratorMismatch: (details) => {
        // 開発中は警告を表示するだけ
        if (process.env.NODE_ENV === 'development') {
          console.warn(
            `プリレンダリングの不一致：${details.entry}は${details.generatedFromId}から生成されましたが、` +
            `${details.matchedId}にマッチしました。\n${details.message}`
          );
        } else {
          // 本番環境ではエラーを投げる
          throw new Error(
            `プリレンダリングの不一致：${details.entry}（${details.message}）`
          );
        }
      }
    }
  }
};

なぜ必要なのか

このハンドラーが解決しようとする問題は、以下のようなケースで発生することがあります：

動的ルートの競合: 例えば、/blog/[slug]と/blog/[...rest]の両方のルートがあり、生成されたパスがどちらにもマッチする場合
レイアウトの変更: ルートを変更した際に、プリレンダリングエントリーが新しいルート構造と整合しない場合
リダイレクト競合: プリレンダリングされたパスが意図していないリダイレクトルールにマッチしてしまう場合

このインターフェースを使用することで、開発者はこのような不一致が発生した際にどのように対応するかをカスタマイズでき、デバッグや問題解決がしやすくなります。

PrerenderEntryGeneratorMismatchHandlerValue

type PrerenderEntryGeneratorMismatchHandlerValue =
	| 'fail'
	| 'warn'
	| 'ignore'
	| PrerenderEntryGeneratorMismatchHandler;

解説

PrerenderEntryGeneratorMismatchHandlerValueは、SvelteKitのプリレンダリング処理中に不一致（ミスマッチ）が発生した場合の対応方法を指定するための型定義です。この型は、文字列リテラルのいずれかまたはカスタムハンドラー関数を受け入れます。

選択可能な値

'fail':
- ミスマッチが発生した場合にビルドプロセスを中断し、エラーを発生させます
- 最も厳格な設定で、プリレンダリングの問題を確実に修正したい場合に使用します
'warn':
- ミスマッチが発生した場合に警告を表示しますが、ビルドプロセスは続行します
- 問題を認識しつつも、ビルドを完了させたい場合に有用です
'ignore':
- ミスマッチを完全に無視し、何の通知もせずにビルドを続行します
- 問題が既知であり、対応が不要な場合に使用します
PrerenderEntryGeneratorMismatchHandler:
- カスタムハンドラー関数を提供して、ミスマッチの詳細情報に基づいて独自の対応を実装できます
- より複雑な条件分岐や、特定のケースのみを無視/警告/失敗させたい場合に有用です

使用例

SvelteKitの設定ファイルでこの型を使用する例：

// svelte.config.js
export default {
  kit: {
    prerender: {
      // 文字列リテラルを使用する簡単な例
      handleEntryGeneratorMismatch: 'warn',
      
      // または、カスタムハンドラー関数を使用する高度な例
      // handleEntryGeneratorMismatch: (details) => {
      //   // 特定のパスパターンのみ無視し、それ以外はエラーにする
      //   if (details.entry.startsWith('/blog/')) {
      //     console.warn(`Blog route mismatch ignored: ${details.entry}`);
      //   } else {
      //     throw new Error(`Prerender mismatch: ${details.message}`);
      //   }
      // }
    }
  }
};