このページは Cloud Translation API によって翻訳されました。

Workbox v3 から v4 に移行する

このガイドでは、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 で問題を報告してください。