Workbox コマンドライン インターフェース(workbox-cli
パッケージに含まれます)は、Workbox と呼ばれる Node.js プログラムで構成されています。このプログラムは、UNIX 互換のコマンドライン環境の Windows、macOS から実行できます。内部で、workbox-cli は workbox-build モジュールをラップし、柔軟な構成で Workbox をコマンドライン ビルドプロセスに統合する簡単な方法を提供します。
CLI をインストールする
Node を使用して CLI をインストールするには、ターミナルで次のコマンドを実行します。
npm install workbox-cli --global
CLI モード
CLI には次の 4 つのモードがあります。
wizard
: プロジェクトの Workbox を設定するための手順ガイド。generateSW
: 完全な Service Worker を生成します。injectManifest
: プロジェクトにプリキャッシュするアセットを挿入します。copyLibraries
: Workbox ライブラリをディレクトリにコピーします。
wizard
ワークボックス ウィザードで、ローカル ディレクトリの設定と事前キャッシュに保存するファイルに関する一連の質問が表示されます。回答に基づいて構成ファイルが生成されます。このファイルは、generateSW
モードで実行する際に使用できます。
ほとんどのデベロッパーは、ワークボックス ウィザードを 1 回実行するだけで済みます。サポートされているビルド構成オプションを使用して、生成される初期構成ファイルを手動でカスタマイズできます。
ウィザードを起動するには、次のコマンドを実行します。
npx workbox-cli wizard
generateSW
Workbox CLI では、構成ファイル(ウィザードで生成されたファイルなど)を使用して完全な Service Worker を生成できます。
次のコマンドを実行します。
npx workbox-cli generateSW path/to/config.js
Workbox の組み込みのプレキャッシュ機能とランタイム キャッシュ機能を使用し、Service Worker の動作をカスタマイズする必要がないデベロッパーは、generateSW
モードを使用することをおすすめします。
generateSW
を使用するケース
- ファイルを事前キャッシュしたい。
- 単純なランタイム キャッシュが必要な場合。
generateSW
を使用すべきでない場合
- Service Worker のその他の機能(ウェブプッシュなど)を使用したい場合。
- 追加のスクリプトをインポートするか、カスタムのキャッシュ戦略のためにロジックを追加する場合。
injectManifest
最終的な Service Worker ファイルをより細かく制御したい場合は、injectManifest
モードを使用できます。このモードでは、Service Worker ファイル(ファイルの場所は config.js で指定)がすでに存在することを前提としています。
workbox injectManifest
が実行されると、ソース Service Worker ファイル内で特定の文字列(デフォルトでは precacheAndRoute(self.__WB_MANIFEST)
)が検索されます。空の配列を事前キャッシュに保存する URL のリストに置き換え、config.js
の構成オプションに基づいて Service Worker ファイルを宛先に書き込みます。ソース Service Worker の残りのコードは、そのまま残ります。
Workbox はこのモードで次のように使用できます。
npx workbox-cli injectManifest path/to/config.js
injectManifest
を使用するケース
- Service Worker をより詳細に制御したい場合。
- ファイルを事前キャッシュしたい。
- ルーティングと戦略をカスタマイズする必要があります。
- Service Worker を他のプラットフォーム機能(ウェブプッシュなど)と併用する場合。
injectManifest
を使用すべきでない場合
- サイトに Service Worker を追加する最も簡単な方法が必要です。
copyLibraries
このモードは、injectManifest
を使用し、CDN を使用する代わりに独自の送信元でホストされている Workbox ライブラリ ファイルを使用する場合に役立ちます。
ファイルを書き込むパスを指定して実行するだけです。
npx workbox-cli copyLibraries third_party/workbox/
ビルドプロセスの統合
Workbox を My Build プロセスと統合する必要がある理由
Workbox プロジェクトには、ウェブアプリの Service Worker を強化するために連携するライブラリが多数含まれています。これらのライブラリを効果的に使用するには、Workbox をウェブアプリのビルドプロセスに統合する必要があります。これにより、Service Worker はウェブアプリのすべての重要なコンテンツを効率的に事前キャッシュし、そのコンテンツを最新の状態に保つことができます。
workbox-cli
は自社のビルドプロセスに適しているか
npm スクリプトを完全にベースとする既存のビルドプロセスがある場合は、workbox-cli
を選択することをおすすめします。
現在ビルドツールとして webpack を使用している場合は、workbox-webback-plugin を使用することをおすすめします。
現在 Gulp、Grunt、またはその他の Node.js ベースのビルドツールを使用している場合は、ビルド スクリプトに workbox-build を統合することをおすすめします。
ビルドプロセスがない場合は、Workbox を使用してアセットを事前キャッシュする前に、ビルドプロセスを作成する必要があります。workbox-cli を手動で実行すると、エラーが発生しやすくなることがあります。また、実行を忘れると、リピーターに古いコンテンツが配信される可能性があります。
セットアップと設定
ローカル プロジェクトの開発依存関係として workbox-cli
をインストールした後、既存のビルドプロセスの npm スクリプトの末尾に workbox
の呼び出しを追加できます。
package.json から:
{
"scripts": {
"build": "my-build-script && workbox <mode> <path/to/config.js>"
}
}
<mode>
は、ユースケースに応じて generateSW
または injectManifest
に置き換え、<path/to/config.js>
は、構成オプションのパスに置き換えます。構成は、workbox wizard
によって自動的に作成されたか、手動で調整された可能性があります。
設定
generateSW
が使用するオプション
すべての構成オプションについては、リファレンス ドキュメントをご覧ください。
injectManifest
が使用するオプション
すべての構成オプションについては、リファレンス ドキュメントをご覧ください。