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

Workbox v3 から v4 に移行する

このガイドでは、Workbox v4 で導入された互換性のない変更に焦点を当て、Workbox v3 からアップグレードする際に必要な変更の例を紹介します。

互換性に対応しない変更

workbox-precaching

プリキャッシュエントリの命名規則が更新されました。これで、URL にリビジョン情報が必要となるエントリ（プリキャッシュマニフェストに revision フィールドを含むエントリ）の場合、そのバージョニング情報は、元の URL に追加された特別な __WB_REVISION__ URL クエリパラメータで、キャッシュキーの一部として保存されます。（以前は、この情報は IndexedDB を使用してキャッシュキーとは別に保存されていました）。

workbox.precaching.precacheAndRoute() によるプリキャッシュを利用しているデベロッパー（最も一般的なユースケース）は、サービスワーカーの構成を変更する必要はありません。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() の呼び出しをサービスワーカーに直接追加するか、GenerateSW モードでビルドツールを使用している場合は新しい cleanupOutdatedCaches: true オプションを設定します。キャッシュのクリーンアップロジックは、キャッシュの命名規則に基づいて古いプリキャッシュを検出するため、デベロッパーはこれらの規則をオーバーライドできるため、安全性を重視して、デフォルトでこの機能を有効にしませんでした。

削除に関する誤検出など、この機能の使用中に問題が発生した場合は、お知らせください。

パラメータの大文字と小文字

workbox.precaching.precacheAndRoute() と workbox.precaching.addRoute() に渡すことができる 2 つのオプションパラメータの名前が変更され、全体的な大文字 / 小文字の規則が標準化されました。ignoreUrlParametersMatching は ignoreURLParametersMatching に、cleanUrls は cleanURLs に変更されました。

workbox-strategies

workbox-strategies でハンドラのインスタンスを作成するには、ほぼ同等の 2 つの方法があります。戦略のコンストラクタを明示的に呼び出すために、factory メソッドのサポートを終了します。

// 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 クラスにはキューにリクエストを追加する方法が 1 つ（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 パッケージと同等の機能を提供します。

workbox-broadcast-update

npm パッケージの名前が workbox-broadcast-update に変更されました。これは、他のモジュールで使用されている命名規則に合わせて変更されたものです。このパッケージは、非推奨となった古い workbox-broadcast-cache-update パッケージと同等の機能を備えています。

workbox-core

Workbox v3 では、workbox.core.LOG_LEVELS 列挙型の値の 1 つを渡す workbox.core.setLogLevel() メソッドで、ログレベルの詳細度を制御できます。workbox.core.logLevel を使用して現在のログレベルを読み取ることもできます。

Workbox v4 では、最新のデベロッパーツールのすべてに豊富なログフィルタリング機能が備わっているため、これらはすべて削除されました（Chrome Dev Tools のコンソール出力のフィルタリングをご覧ください）。

workbox-sw

以前は 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

新しい workbox-window モジュールは、サービスワーカーの登録と更新の検出のプロセスを簡素化し、サービスワーカーで実行されるコードとウェブアプリの window コンテキストで実行されるコード間の通信に標準的な手段を提供します。

workbox-window の使用は任意ですが、デベロッパーの皆様にとって有用なものとなることを願っています。また、必要に応じて、手書きのロジックの一部を移行して使用することを検討してください。workbox-window の使用方法について詳しくは、モジュールのガイドをご覧ください。

移行の例

Workbox v3 から v4 への実際の移行の例については、こちらの pull リクエストをご覧ください。

困ったときは

ほとんどの移行は簡単なはずです。このガイドに記載されていない問題が発生した場合は、GitHub で問題を報告してください。