このガイドでは、Workbox v4 で導入された互換性を破る変更を中心に、Workbox v3 からアップグレードする際に必要な変更の例も示します。
互換性を損なう変更
ワークボックスのプレキャッシュ
事前キャッシュ エントリの命名規則が更新されました。URL のリビジョン情報が必要なエントリ(プリキャッシュ マニフェストの revision
フィールドを含むエントリ)については、元の URL に付加される特別な __WB_REVISION__
URL クエリ パラメータで、そのバージョニング情報がキャッシュキーの一部として保存されるようになりました。(以前は、この情報はキャッシュキーとは別に IndexedDB を使用して保存されていました)。
最も一般的なユースケースである workbox.precaching.precacheAndRoute()
によるプレキャッシュを活用しているデベロッパーは、Service Worker の構成を変更する必要はありません。Workbox v4 にアップグレードすると、ユーザーのキャッシュに保存されたアセットが新しいキャッシュキー形式に自動的に移行され、その後も、事前キャッシュされたリソースは引き続き以前と同じ方法で提供されます。
キャッシュキーの直接の使用
デベロッパーによっては、workbox.precaching.precacheAndRoute()
のコンテキスト外で、事前キャッシュ エントリに直接アクセスしなければならない場合があります。たとえば、画像を事前キャッシュに保存して、ネットワークから実際の画像を取得できない場合に「代替」レスポンスとして使用するような場合です。
Workbox v4 以降で事前キャッシュされたアセットを使用する場合、元の URL を対応するキャッシュキーに変換して、キャッシュ エントリの読み取りに使用できるようにするために、追加の手順が必要になります。そのためには、workbox.precaching.getCacheKeyForURL(originURL)
を呼び出します。
たとえば、'fallback.png'
が事前キャッシュされていることがわかっているとします。
const imageFallbackCacheKey =
workbox.precaching.getCacheKeyForURL('fallback.png');
workbox.routing.setCatchHandler(({event}) => {
switch (event.request.destination) {
case 'image':
return caches.match(imageFallbackCacheKey);
break;
// ...other fallback logic goes here...
}
});
キャッシュに保存されている古いデータのクリーンアップ
Workbox v4 での事前キャッシュに対する変更により、Workbox の以前のバージョンで作成された古い事前キャッシュには互換性がありません。デフォルトではこれらはそのままで、Workbox v3 から Workbox v4 にアップグレードすると、事前にキャッシュに保存されたリソースのコピーが 2 つ作成されます。
これを回避するには、workbox.precaching.cleanupOutdatedCaches()
の呼び出しを Service Worker に直接追加するか、ビルドツールを GenerateSW
モードで使用する場合は新しい cleanupOutdatedCaches: true
オプションを設定します。キャッシュ クリーンアップ ロジックは、キャッシュの命名規則に基づいて動作して古いプリキャッシュを検出します。また、開発者はそれらの規則をオーバーライドすることもできるため、安全性を重視し、デフォルトでは有効化しませんでした。
削除に関する誤検出など、この機能の使用に関して問題が発生した場合は、Google までご連絡ください。
パラメータの大文字表記
workbox.precaching.precacheAndRoute()
と workbox.precaching.addRoute()
に渡すことができる 2 つのオプション パラメータの名前が変更され、全体的な大文字の使用規則が標準化されました。ignoreUrlParametersMatching
は ignoreURLParametersMatching
、cleanUrls
は cleanURLs
に変更されました。
ワークボックス戦略
workbox-strategies
でハンドラのインスタンスを作成する方法は 2 つあります。ほぼ同じ方法です。戦略のコンストラクタを明示的に呼び出すために、ファクトリ メソッドが非推奨になりました。
// This factory method syntax has been deprecated:
const networkFirstStrategy = workbox.strategies.networkFirst({...});
// Instead, use the constructor directly:
// (Note that the class name is Uppercase.)
const networkFirstStrategy = new workbox.strategies.NetworkFirst({...});
ファクトリ メソッドの構文は v4 でも引き続き機能しますが、使用すると警告がログに記録されます。今後の v5 リリースでサポートを削除する前に移行することをおすすめします。
workbox-background-sync
workbox.backgroundSync.Queue
クラスが書き換えられ、リクエストのキューへの追加やリプレイの方法をデベロッパーが柔軟に制御できるようになりました。
v3 の Queue
クラスには、キューにリクエストを追加する単一の方法(addRequest()
メソッド)がありましたが、キューを変更したり、リクエストを削除したりすることはできませんでした。
v4 では、addRequests()
メソッドが削除され、次の配列のようなメソッドが追加されています。
pushRequest()
popRequest()
shiftRequest()
unshiftRequest()
v3 では、Queue
クラスは、リクエストのリプレイのタイミング(requestWillEnqueue
、requestWillReplay
、queueDidReplay
)をモニタリングできるいくつかのコールバックも受け入れていましたが、ほとんどのデベロッパーは、モニタリングに加えて、個々のリクエストを動的に変更、並べ替え、キャンセルする機能など、キューのリプレイ方法を制御する必要があることに気づきました。
v4 では、これらのコールバックが削除され、ブラウザがリプレイが試行されるたびに呼び出される単一の onSync
コールバックに置き換えられました。デフォルトでは、onSync
コールバックは replayRequests()
を呼び出しますが、リプレイプロセスをより細かく制御する必要がある場合は、上記の配列のようなメソッドを使用して、好みに応じてキューをリプレイできます。
カスタム リプレイ ロジックの例を次に示します。
const queue = new workbox.backgroundSync.Queue('my-queue-name', {
onSync: async ({queue}) => {
let entry;
while ((entry = await this.shiftRequest())) {
try {
await fetch(entry.request);
} catch (error) {
console.error('Replay failed for request', entry.request, error);
await this.unshiftRequest(entry);
return;
}
}
console.log('Replay complete!');
},
});
同様に、workbox.backgroundSync.Plugin
クラスは Queue
クラスと同じ引数を受け取る(内部で Queue
インスタンスを作成するため)ため、同じように変更されています。
workbox-expiration(ワークボックス有効期限)
他のモジュールで使用されている命名規則に合わせて、npm
パッケージの名前が workbox-expiration
に変更されました。このパッケージは機能的には、サポートが終了した古い workbox-cache-expiration
パッケージと同等です。
ワークボックス ブロードキャスト アップデート
他のモジュールで使用されている命名規則に合わせて、npm
パッケージの名前が workbox-broadcast-update
に変更されました。このパッケージは機能的には、サポートが終了した古い workbox-broadcast-cache-update
パッケージと同等です。
ワークボックスコア
Workbox v3 では、ログレベルの詳細度を workbox.core.setLogLevel()
メソッドで制御できます。このメソッドには workbox.core.LOG_LEVELS
列挙型の値の 1 つが渡されます。workbox.core.logLevel
を使用して現在のログレベルを読み取ることもできます。
Workbox v4 では、これらはすべて削除されました。最新のすべてのデベロッパー ツールには充実したログのフィルタリング機能が搭載されています(Chrome Dev Tools のコンソール出力のフィルタリングをご覧ください)。
ワークボックスのソフトウェア
以前は workbox
名前空間(workbox-sw
モジュールに対応)で直接公開されていた 2 つのメソッドを workbox.core
に移動しました。「workbox.skipWaiting()
」が「workbox.core.skipWaiting()
」になり、同様に「workbox.clientsClaim()
」が「workbox.core.clientsClaim()
」になりました。
ビルドツールの構成
workbox-cli、workbox-build、workbox-webpack-plugin に渡すことができる一部のオプションの名前が変更されました。オプション名に「Url」が使用されていたものはサポートが終了し、今後は「URL」に置き換えられました。そのため、次のオプション名を使用することをおすすめします。
dontCacheBustURLsMatching
ignoreURLParametersMatching
modifyURLPrefix
templatedURLs
そうしたオプション名の「Url」バリエーションは V4 でも機能しますが、警告メッセージが表示されます。デベロッパーの皆様には、v5 リリースに先立って移行することをおすすめします。
新機能
ワークボックス ウィンドウ
新しい workbox-window
モジュールは、Service Worker の登録プロセスと更新の検出プロセスを簡素化し、Service Worker で実行されているコードとウェブアプリの window
コンテキストで実行されているコードとの間の標準的な通信手段を提供します。
workbox-window
の使用は任意ですが、デベロッパーの皆様のお役に立つことを願っています。また、必要に応じて手書きのロジックを移行して、使用を検討してください。workbox-window
の使用方法について詳しくは、モジュールのガイドをご覧ください。
移行の例
Workbox v3 から v4 への実際の移行の例については、こちらの pull リクエストをご覧ください。
参考情報
ほとんどの移行は簡単に行うことができると考えられます。このガイドに記載されていない問題が発生した場合は、GitHub で問題を報告してください。