Skip to main content

Hooks

Edit this page on GitHub

オプションの src/hooks.js (または src/hooks.ts、または src/hooks/index.js) ファイルはサーバー上で実行される4つの関数 — handle、handleError、getSession、externalFetch — をエクスポートできます。全てオプションです。

このファイルの配置場所は コンフィグ の config.kit.files.hooks で変更することができます。

handle

この関数は SvelteKit のサーバーが リクエスト を受けるたびに (アプリの実行中であろうと、プリレンダリングであろうと) 実行され、レスポンス を決定します。リクエストを表す event オブジェクトと、SvelteKitのルーターを呼び出しそれに応じて(ページをレンダリングしたり、エンドポイントを呼び出したりして)レスポンスを生成する resolve という関数を受け取ります。これにより、レスポンスのヘッダーやボディを変更したり、SvelteKitを完全にバイパスすることができます (例えば、プログラムでエンドポイントを実装する場合など)。

src/hooks.js
ts
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
  if (event.url.pathname.startsWith('/custom')) {
    return new Response('custom response');
  }
 
  const response = await resolve(event);
  return response;
}

静的アセット(プリレンダリング済みのページを含む)に対するリクエストは SvelteKit では処理されません。

未実装の場合、デフォルトでは ({ event, resolve }) => resolve(event) となります。カスタムデータをリクエストに追加してエンドポイントに渡すには、以下のように event.locals オブジェクトにデータを追加します。

src/hooks.js
ts
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
  event.locals.user = await getUserInformation(event.request.headers.get('cookie'));
 
  const response = await resolve(event);
  response.headers.set('x-custom-header', 'potato');
 
  return response;
}

sequence ヘルパー関数を使用すると、複数の handle 関数呼び出しを追加することができます。

resolve はオプションの第2引数をサポートしており、レスポンスのレンダリング方法をより詳細にコントロールすることができます。そのパラメータは、以下のフィールドを持つオブジェクトです:

  • ssr: boolean (default true) — false の場合、サーバーサイドレンダリングする代わりに空の 'shell' ページをレンダリングします
  • transformPage(opts: { html: string }): string — カスタムの変換を HTML に適用します
src/hooks.js
ts
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
  const response = await resolve(event, {
    ssr: !event.url.pathname.startsWith('/admin'),
    transformPage: ({ html }) => html.replace('old', 'new')
  });
 
  return response;
}

サーバーサイドレンダリング を無効にすると、SvelteKit アプリは事実上 シングルページアプリ または SPA になります。ほとんどの場合、これは推奨されません (appendix を参照)。無効にすることが本当に適切かどうかを検討し、すべてのリクエストに対して無効にするのではなく、選択的に無効にしてください。

handleError

もしレンダリング中にエラーがスローされたら、error とそれを引き起こした event を引数にこの関数が呼び出されます。これによってデータをエラートラッキングサービスに送ったり、エラーをコンソールに出力する前にフォーマットをカスタマイズしたりすることができます。

開発中、もし Svelte コードで構文エラーが発生した場合、エラー場所をハイライトする frame プロパティが追加されます。

未実装の場合、SvelteKitはデフォルトのフォーマットでエラーをログ出力します。

src/hooks.js
ts
/** @type {import('@sveltejs/kit').HandleError} */
export async function handleError({ error, event }) {
  // example integration with https://sentry.io/
  Sentry.captureException(error, { event });
}

handleError は例外がキャッチされていない場合にのみ呼び出されます。ページやエンドポイントが明示的に 4xx や 5xx ステータスコードで応答した場合は呼び出されません。

getSession

この関数は、event オブジェクトを引数に取り、クライアントからアクセス可能な session オブジェクトを返します。つまり session オブジェクトはユーザーに公開しても安全なものでなければなりません。この関数はSvelteKitがページをサーバーレンダリングする際に実行されます。

未実装の場合、session は {} です。

src/hooks.js
ts
/** @type {import('@sveltejs/kit').GetSession} */
export function getSession(event) {
  return event.locals.user
    ? {
        user: {
          // only include properties needed client-side —
          // exclude anything else attached to the user
          // like access tokens etc
          name: event.locals.user.name,
          email: event.locals.user.email,
          avatar: event.locals.user.avatar
        }
      }
    : {};
}

session はシリアライズ可能でなければなりません。つまり、関数やカスタムクラスなどを含んではならず、JavaScriptの組み込みデータ型だけでなければいけません

externalFetch

この関数によって、サーバー上で (またはプリレンダリング中に) 実行される load 関数の中で発生する、外部リソースへの fetch リクエストを変更 (または置換) することができます。

例えば、ユーザーがクライアントサイドで https://api.yourapp.com のようなパブリックなURLに移動をするときには、load 関数でそのURLにリクエストを行うかもしれません。しかしSSRでは、(パブリックなインターネットとの間にあるプロキシーやロードバランサーをバイパスして) 直接 API にアクセスするほうが理にかなっている場合があります。

ts
/** @type {import('@sveltejs/kit').ExternalFetch} */
export async function externalFetch(request) {
  if (request.url.startsWith('https://api.yourapp.com/')) {
    // clone the original request, but change the URL
    request = new Request(
      request.url.replace('https://api.yourapp.com/', 'http://localhost:9999/'),
      request
    );
  }
 
  return fetch(request);
}
previous Loading
next Modules
We stand with Ukraine. Donate → We stand with Ukraine. Petition your leaders. Show your support.