ワークボックス ルーティング

Service Worker は、ページのネットワーク リクエストをインターセプトできます。キャッシュされたコンテンツ、ネットワークのコンテンツ、Service Worker で生成されたコンテンツなどを使用してブラウザに応答します。

workbox-routing は、レスポンスを提供するさまざまな関数にこれらのリクエストを簡単に「ルーティング」できるようにするモジュールです。

ルーティングの実行方法

ネットワーク リクエストによって Service Worker のフェッチ イベントが発生すると、workbox-routing は指定されたルートとハンドラを使用してリクエストに応答しようとします。

上述の主な注意点は次のとおりです。

• リクエストの方法は重要です。デフォルトでは、Route は GET リクエストに対して登録されます。他のタイプのリクエストをインターセプトする場合は、メソッドを指定する必要があります。

• ルートの登録順序は重要です。リクエストを処理できる複数の Route が登録されている場合は、最初に登録された Route がリクエストの処理に使用されます。

ルートを登録する方法はいくつかあり、コールバック、正規表現、Route インスタンスを使用できます。

ルートでの照合と処理

ワークボックスの「route」は、ルートがリクエストに一致するかどうかを判断する「マッチング」関数と、リクエストを処理してレスポンスを返す「処理」関数の 2 つの機能にすぎません。

Workbox にはマッチングと処理を行うヘルパーが用意されていますが、別の動作が必要な場合は、カスタムの一致とハンドラ関数を作成するのが最適です。

一致コールバック関数には、ExtendableEvent、Request、信頼できる値を返すことで照合できる URL オブジェクトが渡されます。簡単な例として、次のように特定の URL を照合できます。

const matchCb = ({url, request, event}) => {
  return url.pathname === '/special/url';
};

url または request を調査またはテストすることで、ほとんどのユースケースに対応できます。

ハンドラ コールバック関数には、同じ ExtendableEvent、Request、URL オブジェクトと、params 値（match 関数によって返される値）が渡されます。

const handlerCb = async ({url, request, event, params}) => {
  const response = await fetch(request);
  const responseBody = await response.text();
  return new Response(`${responseBody} <!-- Look Ma. Added Content. -->`, {
    headers: response.headers,
  });
};

ハンドラは、Response に解決される Promise を返す必要があります。この例では、async と await を使用します。内部で、返される Response 値は Promise にラップされます。

これらのコールバックは次のように登録できます。

import {registerRoute} from 'workbox-routing';

registerRoute(matchCb, handlerCb);

唯一の制限は、「match」コールバックは同期的に真の値を返す必要があり、非同期処理は実行できません。これは、Router がフェッチ イベントに同期的に応答するか、他のフェッチ イベントにフォールバックする必要があるためです。

通常、「ハンドラ」コールバックは、workbox-strategies によって提供される方法のいずれかを次のように使用します。

import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';

registerRoute(matchCb, new StaleWhileRevalidate());

このページでは workbox-routing を中心に説明しますが、ワークボックス戦略に関するこれらの戦略の詳細もご覧ください。

正規表現のルートの登録方法

一般的には、「match」コールバックの代わりに正規表現を使用します。Workbox を使用すると、次のように簡単に実装できます。

import {registerRoute} from 'workbox-routing';

registerRoute(new RegExp('/styles/.*\\.css'), handlerCb);

同じ送信元からのリクエストの場合、リクエストの URL が正規表現と一致する限り、この正規表現は一致します。

• https://example.com/styles/main.css
• https://example.com/styles/nested/file.css
• https://example.com/nested/styles/directory.css

ただし、クロスオリジン リクエストの場合、正規表現は URL の先頭と一致する必要があります。これは、正規表現 new RegExp('/styles/.*\\.css') を使用するとサードパーティの CSS ファイルを照合できる可能性が低いためです。

• https://cdn.third-party-site.com/styles/main.css
• https://cdn.third-party-site.com/styles/nested/file.css
• https://cdn.third-party-site.com/nested/styles/directory.css

この動作が必要な場合は、正規表現が URL の先頭と一致するようにする必要があります。https://cdn.third-party-site.com のリクエストを照合する場合は、正規表現 new RegExp('https://cdn\\.third-party-site\\.com.*/styles/.*\\.css') を使用できます。

• https://cdn.third-party-site.com/styles/main.css
• https://cdn.third-party-site.com/styles/nested/file.css
• https://cdn.third-party-site.com/nested/styles/directory.css

ローカルとサードパーティの両方に一致する場合は、正規表現の先頭にワイルドカードを使用できますが、ウェブアプリで予期しない動作が発生しないように注意する必要があります。

ナビゲーション ルートを登録する方法

シングルページ アプリの場合は、NavigationRoute を使用して、すべてのナビゲーション リクエストに対して特定のレスポンスを返すことができます。

import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';

// This assumes /app-shell.html has been precached.
const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler);
registerRoute(navigationRoute);

ユーザーがブラウザでサイトにアクセスすると、そのページのリクエストはナビゲーション リクエストとなり、キャッシュされたページ /app-shell.html が配信されます。（注: workbox-precaching または独自のインストール手順で、ページをキャッシュに保存する必要があります）。

デフォルトでは、すべてのナビゲーション リクエストに応答します。一部の URL にのみレスポンスを返すように制限する場合は、allowlist オプションと denylist オプションを使用して、このルートに一致するページを制限できます。

import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';

// This assumes /app-shell.html has been precached.
const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler, {
  allowlist: [new RegExp('/blog/')],
  denylist: [new RegExp('/blog/restricted/')],
});
registerRoute(navigationRoute);

ただし、URL が allowlist と denylist の両方にある場合、denylist が優先されます。

デフォルト ハンドラの設定

ルートに一致しないリクエストに「ハンドラ」を提供する場合は、デフォルト ハンドラを設定できます。

import {setDefaultHandler} from 'workbox-routing';

setDefaultHandler(({url, event, params}) => {
  // ...
});

キャッチ ハンドラを設定する

いずれかのルートでエラーがスローされた場合は、キャッチ ハンドラを設定することで、キャプチャとグレースフル デグラデーションを行うことができます。

import {setCatchHandler} from 'workbox-routing';

setCatchHandler(({url, event, params}) => {
  ...
});

GET 以外のリクエスト用のルートの定義

デフォルトでは、すべてのルートが GET リクエスト用のものとみなされます。

POST リクエストなど、他のリクエストをルーティングする場合は、ルートの登録時に次のようにメソッドを定義する必要があります。

import {registerRoute} from 'workbox-routing';

registerRoute(matchCb, handlerCb, 'POST');
registerRoute(new RegExp('/api/.*\\.json'), handlerCb, 'POST');

ルーターのロギング

workbox-routing のログを使用して、リクエストのフローを特定できます。このログには、Workbox で処理されている URL がハイライト表示されます。

より詳細な情報が必要な場合は、ログレベルを debug に設定すると、Router で処理されないリクエストのログを表示できます。ログレベルの設定の詳細については、デバッグガイドをご覧ください。

高度な使用方法

ワークボックス ルーターにリクエストが提供されるタイミングをより細かく制御するには、独自の Router インスタンスを作成し、ルーターを使用してリクエストに応答する必要があるときに、そのインスタンスの handleRequest() メソッドを呼び出します。

import {Router} from 'workbox-routing';

const router = new Router();

self.addEventListener('fetch', event => {
  const {request} = event;
  const responsePromise = router.handleRequest({
    event,
    request,
  });
  if (responsePromise) {
    // Router found a route to handle the request.
    event.respondWith(responsePromise);
  } else {
    // No route was found to handle the request.
  }
});

Router を直接使用する場合は、Route クラスか、いずれかの拡張クラスを使用してルートを登録する必要もあります。

import {Route, RegExpRoute, NavigationRoute, Router} from 'workbox-routing';

const router = new Router();
router.registerRoute(new Route(matchCb, handlerCb));
router.registerRoute(new RegExpRoute(new RegExp(...), handlerCb));
router.registerRoute(new NavigationRoute(handlerCb));

workbox-routing.registerRoute(
  capture: string|RegExp|RouteMatchCallback|Route,
  handler?: RouteHandler,
  method?: HTTPMethod,
)

workbox-routing.setCatchHandler(
  handler: RouteHandler,
)

workbox-routing.setDefaultHandler(
  handler: RouteHandler,
)