このガイドでは、Workbox v6 で導入された重大な変更に焦点を当てており、Workbox v5 からアップグレードする際に必要な変更の例も示します。
互換性を損なう変更
ワークボックスコア
workbox-core の skipWaiting() メソッドが install ハンドラを追加しなくなります。これは、self.skipWaiting() を呼び出すだけの場合と同じです。
今後は Workbox v7 で skipWaiting() が削除される可能性が高いため、今後は代わりに self.skipWaiting() を使用してください。
ワークボックスのプレキャッシュ
- HTTP リダイレクトに対応する URL のクロスオリジン HTML ドキュメントは、
workbox-precachingによるナビゲーション リクエストの処理に使用できなくなりました。このようなシナリオは、一般的にはめったにありません。 fbclidURL クエリ パラメータが、特定のリクエストに対して事前キャッシュされたレスポンスを検索するときにworkbox-precachingで無視されるようになりました。PrecacheControllerコンストラクタは、文字列ではなく、特定のプロパティを持つオブジェクトをパラメータとして受け取るようになりました。このオブジェクトは、cacheName（v5 でコンストラクタに渡された文字列と同じ目的を果たす）、plugins（v5 のaddPlugins()メソッドの代わり）、fallbackToNetwork（v5 でcreateHandler()および `createHandlerBoundToURL() に渡された同様のオプションに置き換わる）プロパティをサポートしています。PrecacheControllerのinstall()メソッドとactivate()メソッドはパラメータを 1 つだけ受け取るようになりました。このパラメータは、それぞれ対応するInstallEventまたはActivateEventに設定する必要があります。addRoute()メソッドがPrecacheControllerから削除されました。代わりに、新しいPrecacheRouteクラスを使用して、登録可能なルートを作成できます。precacheAndRoute()メソッドがPrecacheControllerから削除されました。（workbox-precachingモジュールによってエクスポートされた静的ヘルパー メソッドとして引き続き存在します）。代わりにPrecacheRouteを使用できるため、削除されました。createMatchCalback()メソッドがPrecacheControllerから削除されました。代わりに新しいPrecacheRouteを使用できます。createHandler()メソッドがPrecacheControllerから削除されました。代わりに、PrecacheControllerオブジェクトのstrategyプロパティを使用してリクエストを処理できます。createHandler()静的エクスポートは、すでにworkbox-precachingモジュールから削除されています。代わりに、PrecacheControllerインスタンスを作成し、そのstrategyプロパティを使用する必要があります。precacheAndRoute()で登録されたルートは、内部でworkbox-routingのRouterクラスを使用する「実際の」ルートになりました。そのため、registerRoute()とprecacheAndRoute()の呼び出しをインターリーブすると、ルートの評価順序が異なる可能性があります。
ワークボックス ルーティング
setDefaultHandler() メソッドは、適用される HTTP メソッドに対応するオプションの 2 番目のパラメータを受け取るようになりました（デフォルトは 'GET'）。
setDefaultHandler()を使用し、すべてのリクエストがGETの場合は、変更の必要はありません。GET（POST、PUTなど）以外のリクエストがある場合、setDefaultHandler()と指定すると、リクエストは一致しなくなります。
ビルド構成
workbox-build と workbox-cli の getManifest モードと injectManifest モードの mode オプションは、サポートされることが想定されていなかったため、削除されました。これは、InjectManifest プラグインで mode をサポートしている workbox-webpack-plugin には適用されません。
Build Tools には Node.js v10 以降が必要
v10 より前のバージョンの Node.js は、workbox-webpack-plugin、workbox-build、workbox-cli でサポートされなくなりました。v8 より前のバージョンの Node.js を実行している場合は、ランタイムをサポートされているバージョンに更新してください。
新たな改善点
ワークボックス戦略
Workbox v6 では、サードパーティ デベロッパーが独自の Workbox 戦略を定義できる新しい方法が導入されています。これにより、サードパーティ デベロッパーは、Workbox をニーズを満たす方法で拡張できます。
新しい Strategy 基本クラス
v6 では、すべての Workbox Strategy クラスが、新しい Strategy 基本クラスを拡張する必要があります。組み込みの戦略はすべて、これに対応するために書き換えられました。
Strategy 基本クラスは、主に次の 2 つの役割を担います。
- すべての戦略ハンドラに共通のプラグインのライフサイクル コールバックを呼び出す（例: 開始、応答、終了）。
- 戦略が処理する個々のリクエストの状態を管理できる「handler」インスタンスを作成する。
新しい「handler」クラス
以前、内部モジュールで fetchWrapper と cacheWrapper を呼び出す必要がありました。これらは、その名前が示すように、さまざまなフェッチ API とキャッシュ API をフックでライフサイクルにラップします。これは現在プラグインを機能させるメカニズムですが、デベロッパーには公開されていません。
新しい「ハンドラ」クラスである StrategyHandler はこれらのメソッドを公開します。これにより、カスタム戦略は fetch() または cacheMatch() を呼び出し、戦略インスタンスに追加されたプラグインを自動的に呼び出すことができます。
このクラスにより、デベロッパーは、戦略に固有の独自のカスタム ライフサイクル コールバックを追加することも可能になります。これらは、既存のプラグイン インターフェースで「動作」するだけです。
新しいプラグインのライフサイクル状態
Workbox v5 では、プラグインはステートレスです。つまり、/index.html のリクエストによって requestWillFetch コールバックと cachedResponseWillBeUsed コールバックの両方がトリガーされた場合、この 2 つのコールバックは相互に通信する手段がなく、同じリクエストによってトリガーされたことを把握できません。
v6 では、すべてのプラグイン コールバックに新しい state オブジェクトも渡されます。この状態オブジェクトは、この特定のプラグイン オブジェクトとこの戦略呼び出し（handle() の呼び出し）に固有になります。これによりデベロッパーは、同じプラグイン内の別のコールバックの動作に基づいて条件付きでなんらかの処理を行えるプラグインを作成できます（例: requestWillFetch の実行と fetchDidSucceed または fetchDidFail の実行時間の差分を計算する）。
新しいプラグインのライフサイクル コールバック
新しいプラグインのライフサイクル コールバックが追加され、デベロッパーはプラグインのライフサイクルの状態を最大限に活用できるようになりました。
handlerWillStart: ハンドラ ロジックの実行が開始する前に呼び出されます。このコールバックは、ハンドラの初期状態の設定（開始時間の記録など）に使用できます。handlerWillRespond: 戦略のhandle()メソッドがレスポンスを返す前に呼び出されます。このコールバックを使用すると、ルートハンドラやその他のカスタム ロジックにレスポンスを返す前にレスポンスを変更できます。handlerDidRespond: 戦略のhandle()メソッドがレスポンスを返した後に呼び出されます。このコールバックは、他のプラグインで変更された場合など、最終的なレスポンスの詳細を記録するために使用できます。handlerDidComplete: この戦略の呼び出しによってイベントに追加されたすべての extend ライフタイム Promise が終了した後に呼び出されます。このコールバックは、ハンドラの処理が完了するまで待機する必要があるデータ（キャッシュ ヒットのステータス、キャッシュ レイテンシ、ネットワーク レイテンシなど）の報告に使用できます。handlerDidError: ハンドラがどのソースからも有効なレスポンスを送信できない場合に呼び出されます。このコールバックを使用すると、ネットワーク エラーの代わりに「代替」コンテンツを提供できます。
独自のカスタム戦略を実装するデベロッパーは、これらのコールバックを自身で呼び出す必要はありません。すべての処理は、新しい Strategy 基本クラスによって処理されます。
ハンドラ向けのより正確な TypeScript 型
さまざまなコールバック メソッドの TypeScript 定義が正規化されました。これにより、TypeScript を使用して独自のコードを記述してハンドラを実装または呼び出すデベロッパーの利便性が向上します。
ワークボックス ウィンドウ
新しい messageSkipWait() メソッド
新しいメソッド messageSkipWaiting() が workbox-window モジュールに追加されました。これにより、「待機中」の Service Worker に有効化を指示するプロセスが簡素化されます。これにより、次のような改善が行われます。
- 事実上の標準のメッセージ本文である
{type: 'SKIP_WAITING'}を使用してpostMessage()を呼び出します。Workbox によって生成された Service Worker がこれを確認し、skipWaiting()をトリガーします。 - このメッセージを送信する正しい「待機中」の Service Worker が選択されます。これは、
workbox-windowの登録に使用した Service Worker とは異なる場合でも同様です。
「外部」イベントが削除され、isExternal プロパティに置き換えられました。
workbox-window のすべての "external" イベントが、isExternal プロパティが true に設定された「normal」イベントに代わりました。これにより、区別を重視するデベロッパーは引き続きそれを検出でき、知る必要のないデベロッパーはプロパティを無視できます。
クリーナー「ユーザーにページの再読み込みを提供する」のレシピ
上記の両方の変更により、「ユーザーにページの再読み込みを提供する」方法を簡素化できます。
MULTI_LINE_CODE_PLACEHOLDER_0
ワークボックス ルーティング
新しいブール値パラメータ sameOrigin が、workbox-routing で使用される matchCallback 関数に渡されます。同一オリジンの URL に対するリクエストの場合は true に設定され、そうでない場合は false に設定されます。
これにより、次のような一般的なボイラープレートが簡素化されます。
MULTI_LINE_CODE_PLACEHOLDER_1
workbox-expiration の matchOptions
これで、workbox-expiration で matchOptions を設定できるようになりました。これは、CacheQueryOptions として基になる cache.delete() 呼び出しに渡されます。（ほとんどのデベロッパーは、これを行う必要はありません）。
ワークボックスのプレキャッシュ
ワークボックス戦略を使用する
workbox-strategies をベースとして使用するように workbox-precaching を書き換えました。これにより、互換性を破る変更が生じることはありません。また、2 つのモジュールがネットワークとキャッシュにアクセスする方法の長期的な一貫性が向上します。
事前キャッシュでエントリが一括ではなく 1 つずつ処理されるようになりました。
workbox-precaching が更新され、プリキャッシュ マニフェストのエントリが一度にリクエストされてキャッシュされるのが 1 つだけになりました。一度にリクエストとキャッシュは行わず、スロットリングの方法はブラウザに任せます。
これにより、事前キャッシュ中に net::ERR_INSUFFICIENT_RESOURCES エラーが発生する可能性を減らし、ウェブアプリによる事前キャッシュと同時リクエスト間の帯域幅の競合も減らすことができます。
PrecacheFallbackPlugin によってオフラインのフォールバックが簡単に
workbox-precaching に PrecacheFallbackPlugin が追加されました。これにより、v6 で追加された新しい handlerDidError ライフサイクル メソッドが実装されます。
これにより、事前にキャッシュされた URL を、他の方法ではレスポンスを利用できない場合の「代替」として簡単に指定できます。プラグインは、必要とするリビジョン パラメータを含め、事前キャッシュされた URL に対して正しいキャッシュキーを適切に作成します。
NetworkOnly 戦略でナビゲーション リクエストに対するレスポンスを生成できない場合（つまり、カスタムのオフライン HTML ページを表示する場合）に、事前キャッシュされた /offline.html で応答するためにこれを使用する例を次に示します。
MULTI_LINE_CODE_PLACEHOLDER_2
ランタイム キャッシュでの precacheFallback
Service Worker を手動で記述する代わりに generateSW を使用して Service Worker を作成する場合は、runtimeCaching の新しい precacheFallback 構成オプションを使用して同じことを実現できます。
{
// ... other generateSW config options...
runtimeCaching: [{
urlPattern: ({request}) => request.mode === 'navigate',
handler: 'NetworkOnly',
options: {
precacheFallback: {
// This URL needs to be included in your precache manifest.
fallbackURL: '/offline.html',
},
},
}],
}
ヘルプ
ほとんどの移行は簡単であると想定しています。このガイドで取り上げられていない問題が発生した場合は、GitHub で問題を報告してお知らせください。