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

よっしー

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

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

背景
@sveltejs/kit
1. RequestEvent
2. 解説
おわりに

背景

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

@sveltejs/kit

RequestEvent

interface RequestEvent
    Params extends Partial<Record<string, string>> = Partial
        Record<string, string>
    >,
    RouteId extends string | null = string | null
> {…}

cookies: Cookies;

現在のリクエストに関連するクッキーの取得または設定

fetch: typeof fetch;

fetchはネイティブのfetch Web APIと同等で、以下の追加機能があります：

サーバー上で認証付きリクエストを行うことができます（ページリクエストのcookieとauthorizationヘッダーを継承します）
サーバー上で相対リクエストを行うことができます（通常、サーバーコンテキストで使用する場合、fetchはオリジン付きのURLが必要です）
内部リクエスト（例：+server.jsルート用）は、サーバー上で実行時にHTTPコールのオーバーヘッドなしで直接ハンドラー関数に送られます
サーバーサイドレンダリング中、Responseオブジェクトのtextおよびjsonメソッドをフックすることで、レスポンスがキャプチャされレンダリングされたHTMLにインライン化されます。ヘッダーはfilterSerializedResponseHeadersで明示的に含まれない限り、シリアライズされません
ハイドレーション中、レスポンスはHTMLから読み取られ、一貫性が保証され追加のネットワークリクエストが防止されます
クッキーを使用した認証付きリクエストの作成についての詳細はこちらで学べます

getClientAddress: () => string;

アダプターによって設定されるクライアントのIPアドレス

locals: App.Locals;

server handle hook内でリクエストに追加されたカスタムデータを含みます

params: Params;

現在のルートのパラメータ – 例：/blog/[slug]のようなルートに対して、{ slug: string }オブジェクト

platform: Readonly<App.Platform> | undefined;

アダプターを通じて利用可能になる追加データ

request: Request;

元のリクエストオブジェクト

route: {…}

現在のルートに関する情報

id: RouteId;

現在のルートのID – 例：src/routes/blog/[slug]に対して、/blog/[slug]となります

setHeaders: (headers: Record<string, string>) => void;

レスポンスにヘッダーを設定する必要がある場合、このメソッドを使用できます。これは、例えばページをキャッシュしたい場合に便利です：
src/routes/blog/+page

export async function load({ fetch, setHeaders }) {
    const url = `https://cms.example.com/articles.json`;
    const response = await fetch(url);

    setHeaders({
        age: response.headers.get('age'),
        'cache-control': response.headers.get('cache-control')
    });

    return response.json();
}

同じヘッダーを複数回設定すること（別々のload関数であっても）はエラーとなります – 特定のヘッダーは1回しか設定できません。
setHeadersでset-cookieヘッダーを追加することはできません – 代わりにcookies APIを使用してください。

url: URL;

リクエストされたURL

isDataRequest: boolean;

クライアントから+page/layout.server.jsデータを要求するリクエストの場合はtrue。この場合、urlプロパティからデータリクエストに関連する内部情報が削除されます。この区別が重要な場合は、このプロパティを使用してください。

isSubRequest: boolean;

実際にHTTPリクエストを行うオーバーヘッドなしでSvelteKitから来る+server.js呼び出しの場合はtrue。これは、サーバー上で同一オリジンのfetchリクエストを行う場合に発生します。

解説

これはSvelteKitにおけるサーバーサイドのリクエストを処理するための重要なインターフェースです。各エンドポイントやサーバーサイドのロード関数で利用できる情報とメソッドを提供します。

主な重要コンポーネントを見ていきましょう：

1. クッキーとフェッチの処理

cookies: クッキーの読み書きを管理します
fetch: 通常のフェッチAPIを拡張した機能を提供します
サーバーサイドでの認証付きリクエスト
相対パスでのリクエスト
パフォーマンス最適化された内部リクエスト

2. ルーティング関連

params: URLパラメータを取得できます
route.id: 現在のルートのIDを提供します
url: リクエストされたURLの情報を提供します

3. レスポンス制御

setHeaders: レスポンスヘッダーを設定できます
キャッシュ制御などに利用
同じヘッダーの重複設定は禁止
クッキー設定には専用APIを使用

4. リクエストの種類の判別

isDataRequest: クライアントサイドのデータ取得リクエストかどうか
isSubRequest: 内部的なサブリクエストかどうか

5. カスタマイズと拡張

locals: サーバーサイドでカスタムデータを追加可能
platform: アダプター経由で追加機能を利用可能

実践的な使用例

export async function load({ params, fetch, setHeaders }) {
    // URLパラメータの利用
    const { slug } = params;

    // 外部APIからのデータ取得
    const response = await fetch(`/api/articles/${slug}`);

    // キャッシュヘッダーの設定
    setHeaders({
        'cache-control': 'max-age=3600'
    });

    return {
        article: await response.json()
    };
}

このインターフェースは、SvelteKitアプリケーションでサーバーサイドの処理を行う際の基盤となる重要な要素です。特にSSRやAPIエンドポイントの実装時に頻繁に利用することになります。