このガイドでは、Workbox v6 で導入された重大な変更に焦点を当てており、Workbox v5 からアップグレードする際に必要な変更の例も示します。
互換性を損なう変更
ワークボックスコア
workbox-core
の skipWaiting()
メソッドが install
ハンドラを追加しなくなります。これは、self.skipWaiting()
を呼び出すだけの場合と同じです。
今後は Workbox v7 で skipWaiting()
が削除される可能性が高いため、今後は代わりに self.skipWaiting()
を使用してください。
ワークボックスのプレキャッシュ
- HTTP リダイレクトに対応する URL のクロスオリジン HTML ドキュメントは、
workbox-precaching
によるナビゲーション リクエストの処理に使用できなくなりました。このようなシナリオは、一般的にはめったにありません。 fbclid
URL クエリ パラメータが、特定のリクエストに対して事前キャッシュされたレスポンスを検索するときに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 で問題を報告してお知らせください。