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

workbox-webpack-plugin

Workbox には 2 つの webpack プラグインがあります。1 つは完全な Service Worker を生成するもので、もう 1 つは Service Worker ファイルに挿入されるプリキャッシュ対象のアセットのリストを生成するプラグインです。

プラグインは、workbox-webpack-plugin モジュールの GenerateSW と InjectManifest という 2 つのクラスとして実装されます。以下の質問への回答は、使用するプラグインと構成を選択する際の参考になります。

使用するプラグイン

`GenerateSW`

GenerateSW プラグインは、Service Worker ファイルを作成して webpack アセットパイプラインに追加します。

`GenerateSW` を使用するタイミング

ファイルをプリキャッシュする必要がある。
シンプルなランタイムキャッシュが必要である。

`GenerateSW` を使用すべきでない場合

他の Service Worker 機能（ウェブプッシュなど）を使用する必要がある。
追加のスクリプトをインポートする、またはカスタムキャッシュ戦略のロジックを追加する。

`InjectManifest`

InjectManifest プラグインは、プリキャッシュする URL のリストを生成し、そのプリキャッシュマニフェストを既存の Service Worker ファイルに追加します。それ以外は、ファイルはそのまま残ります。

`InjectManifest` を使用するタイミング

サービスワーカーをより細かく制御したい。
ファイルをプリキャッシュする必要がある。
ルーティングと戦略をカスタマイズする必要があります。
サービスワーカーを他のプラットフォーム機能（ウェブプッシュなど）で使用したい場合。

`InjectManifest` を使用すべきでない場合

サイトに Service Worker を追加する最も簡単な方法を探しています。

GenerateSW プラグイン

GenerateSW プラグインを webpack 構成に次のように追加できます。

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      navigateFallback: '...',
      runtimeCaching: [{
        // Routing via a matchCallback function:
        urlPattern: ({request, url}) => ...,
        handler: '...',
        options: {
          cacheName: '...',
          expiration: {
            maxEntries: ...,
          },
        },
      }, {
        // Routing via a RegExp:
        urlPattern: new RegExp('...'),
        handler: '...',
        options: {
          cacheName: '...',
          plugins: [..., ...],
        },
      }],
      skipWaiting: ...,
    }),
  ],
};

これにより、構成で取得されたすべての webpack アセットと、指定されたランタイムキャッシュルールに対してプリキャッシュが設定された Service Worker が生成されます。

構成オプションの一覧については、リファレンスドキュメントをご覧ください。

`InjectManifest` プラグイン

次のように、InjectManifest プラグインを webpack の構成に追加できます。

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      swSrc: '...',
    }),
  ],
};

これにより、構成で取得された webpack アセットに基づいてプリキャッシュマニフェストが作成され、バンドルされてコンパイルされた Service Worker ファイルに挿入されます。

構成オプションの一覧については、リファレンスドキュメントをご覧ください。

その他の情報

大規模な webpack ビルドのコンテキスト内でプラグジンを使用する方法については、webpack のドキュメントのプログレッシブウェブアプリケーションのセクションをご覧ください。

型

GenerateSW

このクラスは、webpack コンパイルプロセスの一部として、すぐに使用できる新しいサービスワーカーファイルを作成できます。

webpack 構成の plugins 配列で GenerateSW のインスタンスを使用します。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

プロパティ

コンストラクタ

void

GenerateSW のインスタンスを作成します。

constructor 関数は次のようになります。
```
(config?: GenerateSWConfig) => {...}
```
- config
  
  GenerateSWConfig（省略可）
- 戻り値
  GenerateSW
config

GenerateSWConfig

GenerateSWConfig

プロパティ

additionalManifestEntries

（string | ManifestEntry）[] 省略可

プリキャッシュに登録するエントリのリストと、ビルド構成の一部として生成されるエントリ。
babelPresetEnvTargets

string[] 省略可
デフォルト値は: ["chrome >= 56"]

Service Worker バンドルのトランスパイル時に babel-preset-env に渡すターゲット。
cacheId

文字列（省略可）

キャッシュ名の先頭に追加する ID（省略可）。これは主に、複数のサイトが同じ http://localhost:port オリジンから提供される可能性があるローカル開発に役立ちます。
チャンク

string[] 省略可

対応する出力ファイルがプリキャッシュマニフェストに含める必要がある 1 つ以上のチャンク名。
cleanupOutdatedCaches

ブール値（省略可）
デフォルト値は false です。

Workbox で、互換性のない古いバージョンによって作成されたプリキャッシュを識別して削除するかどうか。
clientsClaim

ブール値（省略可）
デフォルト値は false

Service Worker が有効になり次第、既存のクライアントの制御を開始するかどうか。
directoryIndex

文字列（省略可）

/ で終わる URL のナビゲーションリクエストがプリキャッシュ URL と一致しない場合、この値が URL に追加され、プリキャッシュとの一致が確認されます。これは、ウェブサーバーがディレクトリインデックスに使用しているものに設定する必要があります。
disableDevLogs

ブール値（省略可）
デフォルト値は false です。
dontCacheBustURLsMatching

RegExp（省略可）

これに一致するアセットは、URL で一意のバージョンが設定されていると見なされ、プリキャッシュの入力時に実行される通常の HTTP キャッシュ破壊から除外されます。必須ではありませんが、既存のビルドプロセスで各ファイル名に [hash] 値がすでに挿入されている場合は、プリキャッシュ時に消費される帯域幅を削減するため、それを検出する RegExp を指定することをおすすめします。
除外

(string | RegExp | function)[] 省略可

プリキャッシュマニフェストからアセットを除外するために使用される 1 つ以上の指定子。これは、webpack の標準 exclude オプションと同じルールに従って解釈されます。指定しない場合、デフォルト値は [/\.map$/, /^manifest.*\.js$] です。
excludeChunks

string[] 省略可

対応する出力ファイルをプリキャッシュマニフェストから除外する 1 つ以上のチャンク名。
ignoreURLParametersMatching

RegExp[] 省略可

この配列内のいずれかの正規表現と一致する検索パラメータ名は、プリキャッシュの一致を探す前に削除されます。これは、トラフィックの発生元の追跡に使用される URL パラメータなどを含む URL をユーザーがリクエストする可能性がある場合に便利です。指定しない場合、デフォルト値は [/^utm_/, /^fbclid$/] です。
importScripts

string[] 省略可

生成された Service Worker ファイル内の importScripts() に渡す必要がある JavaScript ファイルのリスト。これは、Workbox に最上位の Service Worker ファイルを作成させ、プッシュイベントリスナーなどの追加コードを含める場合に便利です。
importScriptsViaChunks

string[] 省略可

webpack チャンクの 1 つ以上の名前。これらのチャンクのコンテンツは、importScripts() の呼び出しを介して、生成された Service Worker に含まれます。
含む

(string | RegExp | function)[] 省略可

プリキャッシュマニフェストにアセットを含めるために使用される 1 つ以上の指定子。これは、webpack の標準 include オプションと同じルールに従って解釈されます。
inlineWorkboxRuntime

ブール値（省略可）
デフォルト値は false

Workbox ライブラリのランタイムコードを最上位の Service Worker に含めるか、または、Service Worker とともにデプロイする必要がある別のファイルに分割するか。ランタイムを分離すると、トップレベルの Service Worker が変更されるたびにユーザーが Workbox コードを再ダウンロードする必要がなくなります。
manifestEntries

ManifestEntry[] 省略可
manifestTransforms

ManifestTransform[] 省略可

生成されたマニフェストに対して順番に適用される 1 つ以上の関数。modifyURLPrefix または dontCacheBustURLsMatching も指定されている場合、対応する変換が最初に適用されます。
maximumFileSizeToCacheInBytes

number（省略可）
デフォルト値は 2097152 です。

この値は、事前キャッシュに保存されるファイルの最大サイズを決定するために使用できます。これにより、パターンのいずれかと誤って一致してしまった可能性がある非常に大きなファイルを誤ってプリキャッシュするのを防ぐことができます。
モード

文字列（省略可）

「production」に設定すると、デバッグ情報を除外した最適化されたサービスワーカーバンドルが生成されます。ここで明示的に構成しない場合、現在の webpack コンパイル時に構成された mode 値が使用されます。
modifyURLPrefix

オブジェクト（省略可）

文字列の接頭辞を置換文字列値にマッピングするオブジェクト。これは、ウェブホスティング設定がローカルファイルシステムの設定と一致しない場合などに、マニフェストエントリからパス接頭辞を削除または追加するために使用できます。より柔軟な方法として、manifestTransforms オプションを使用して、指定したロジックを使用してマニフェストのエントリを変更する関数を指定することもできます。

使用例:
```
// Replace a '/dist/' prefix with '/', and also prepend
// '/static' to every URL.
modifyURLPrefix: {
  '/dist/': '/',
  '': '/static',
}
```
navigateFallback

文字列（省略可）
デフォルト値: null

指定すると、プリキャッシュされていない URL に対するすべてのナビゲーションリクエストは、指定された URL の HTML で処理されます。プリキャッシュマニフェストに記載されている HTML ドキュメントの URL を渡す必要があります。これは、すべてのナビゲーションで共通の App Shell HTML を使用するシングルページアプリのシナリオで使用することを想定しています。
navigateFallbackAllowlist

RegExp[] 省略可

設定された navigateFallback 動作を適用する URL を制限する正規表現の配列（省略可）。これは、サイトの URL のサブセットのみをシングルページアプリの一部として扱う場合に便利です。navigateFallbackDenylist と navigateFallbackAllowlist の両方が構成されている場合、拒否リストが優先されます。

注: これらの正規表現は、ナビゲーション中にすべてのリンク先 URL に対して評価される場合があります。複雑な正規表現は使用しないでください。ユーザーがサイトを操作するときに遅延が発生することがあります。
navigateFallbackDenylist

RegExp[] 省略可

構成された navigateFallback 動作が適用される URL を制限する正規表現の配列（省略可）。これは、サイトの URL のサブセットのみを単一ページアプリの一部として扱う場合に便利です。navigateFallbackDenylist と navigateFallbackAllowlist の両方が設定されている場合は、拒否リストが優先されます。

注: これらの正規表現は、ナビゲーション中にすべてのリンク先 URL に対して評価される場合があります。複雑な正規表現は使用しないでください。使用すると、サイトのナビゲーション時に遅延が発生する可能性があります。
navigationPreload

ブール値（省略可）
デフォルト値は false です。

生成された Service Worker でナビゲーションのプリロードを有効にするかどうか。true に設定する場合は、runtimeCaching を使用して、ナビゲーションリクエストに一致する適切なレスポンス戦略を設定し、プリロードされたレスポンスを使用する必要があります。
offlineGoogleAnalytics

boolean | GoogleAnalyticsInitializeOptions 省略可
デフォルト値は false です。

オフライン Google アナリティクスのサポートを含めるかどうかを制御します。true の場合、workbox-google-analytics の initialize() への呼び出しが生成された Service Worker に追加されます。Object に設定すると、そのオブジェクトが initialize() 呼び出しに渡され、動作をカスタマイズできるようになります。
runtimeCaching

RuntimeCaching[] 省略可

Workbox のビルドツールを使用してサービスワーカーを生成する場合は、1 つ以上のランタイムキャッシュ構成を指定できます。これらは、ユーザーが定義した一致とハンドラ構成を使用して workbox-routing.registerRoute 呼び出しに変換されます。

すべてのオプションについては、workbox-build.RuntimeCaching のドキュメントをご覧ください。次の例は、2 つのランタイムルートが定義された一般的な構成を示しています。
skipWaiting

ブール値（省略可）
デフォルト値は false

生成された Service Worker に skipWaiting() への無条件呼び出しを追加するかどうか。false の場合、代わりに message リスナーが追加され、クライアントページは待機中のサービスワーカーで postMessage({type: 'SKIP_WAITING'}) を呼び出して skipWaiting() をトリガーできるようになります。
ソースマップ

ブール値（省略可）
デフォルト値は true

生成された Service Worker ファイルのソースマップを作成するかどうか。
swDest

文字列（省略可）
デフォルト値は「service-worker.js」です。

このプラグインによって作成された Service Worker ファイルのアセット名。

InjectManifest

このクラスでは、swSrc を介して提供される Service Worker ファイルをコンパイルし、その Service Worker に URL のリストとリビジョン情報を挿入し、webpack アセットパイプラインに基づいてプリキャッシュできます。

webpack 構成の plugins 配列で InjectManifest のインスタンスを使用します。

このプラグインは、マニフェストの挿入に加えて、メインの webpack 構成のオプションを使用して swSrc ファイルのコンパイルを実行します。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new InjectManifest({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  swSrc: '...',
});

プロパティ

コンストラクタ

void

InjectManifest のインスタンスを作成します。

constructor 関数は次のようになります。
```
(config: WebpackInjectManifestOptions) => {...}
```
- config
  
  WebpackInjectManifestOptions
- 戻り値
  InjectManifest
config

WebpackInjectManifestOptions

workbox-webpack-plugin

使用するプラグイン

GenerateSW

GenerateSW を使用するタイミング

GenerateSW を使用すべきでない場合

InjectManifest

InjectManifest を使用するタイミング

InjectManifest を使用すべきでない場合

GenerateSW プラグイン

InjectManifest プラグイン

その他の情報

型

GenerateSW

プロパティ

GenerateSWConfig

プロパティ

InjectManifest

プロパティ

プロパティ

default

タイプ

プロパティ

`GenerateSW`

`GenerateSW` を使用するタイミング

`GenerateSW` を使用すべきでない場合

`InjectManifest`

`InjectManifest` を使用するタイミング

`InjectManifest` を使用すべきでない場合

`InjectManifest` プラグイン