workbox-webpack-plugin

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

プラグインは、workbox-webpack-plugin モジュールで、GenerateSWInjectManifest という 2 つのクラスとして実装されています。次の質問への回答は、使用する適切なプラグインと構成を選択するのに役立ちます。

使用するプラグイン

GenerateSW

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

GenerateSW を使用するケース

  • ファイルを事前キャッシュしたい。
  • 単純なランタイム キャッシュが必要な場合。

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

  • Service Worker のその他の機能(ウェブプッシュなど)を使用したい場合。
  • 追加のスクリプトをインポートするか、カスタムのキャッシュ戦略のためにロジックを追加する場合。

InjectManifest

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

InjectManifest を使用するケース

  • Service Worker をより詳細に制御したい場合。
  • ファイルを事前キャッシュしたい。
  • ルーティングと戦略をカスタマイズする必要があります。
  • Service Worker を他のプラットフォーム機能(ウェブプッシュなど)と併用する場合。

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 のコンパイル プロセスの一環として、すぐに使用できる新しい Service Worker ファイルの作成をサポートしています。

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: ...,
});

プロパティ

GenerateSWConfig

プロパティ

  • additionalManifestEntries

    (文字列 | ManifestEntry)[] 省略可

    ビルド構成の一部として生成されるエントリに加えて、事前キャッシュに保存されるエントリのリスト。

  • babelPresetEnvTargets

    string[] 省略可

    デフォルト値は ["chrome >= 56"] です。

    Service Worker バンドルをトランスパイルするときに babel-preset-env に渡すターゲット

  • cacheId

    string(省略可)

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

  • チャンク

    string[] 省略可

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

  • cleanupOutdatedCaches

    ブール値(省略可)

    デフォルト値は false です。

    Workbox が、互換性のない古いバージョンで作成された事前キャッシュの識別と削除を試行するかどうか。

  • clientsClaim

    ブール値(省略可)

    デフォルト値は false です。

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

  • directoryIndex

    string(省略可)

    末尾が / の 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[](省略可)

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

  • importScripts

    string[] 省略可

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

  • 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 です。

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

  • モード

    string(省略可)

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

  • modifyURLPrefix

    オブジェクト 省略可

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

    使用例:

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

    string(省略可)

    デフォルト値は null です。

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

  • navigateFallbackAllowlist

    RegExp[](省略可)

    構成された navigateFallback の動作を適用する URL を制限する正規表現の配列(省略可)。これは、サイトの URL のサブセットのみを Single Page App の一部として扱う場合に便利です。navigateFallbackDenylistnavigateFallbackAllowlist の両方が設定されている場合、拒否リストが優先されます。

    : これらの RegExp は、ナビゲーション中にすべてのリンク先 URL に対して評価される場合があります。複雑な RegExps は使用しないでください。ユーザーがサイトを移動する際に遅延が発生する可能性があるためです。

  • navigateFallbackDenylist

    RegExp[](省略可)

    構成された navigateFallback の動作を適用する URL を制限する正規表現の配列(省略可)。これは、サイトの URL のサブセットのみを Single Page App の一部として扱う必要がある場合に便利です。navigateFallbackDenylistnavigateFallbackAllowlist の両方が設定されている場合、拒否リストが優先されます。

    : これらの RegExp は、ナビゲーション中にすべてのリンク先 URL に対して評価される場合があります。複雑な RegExps は使用しないでください。ユーザーがサイトを移動する際に遅延が発生する可能性があるためです。

  • navigationPreload

    ブール値(省略可)

    デフォルト値は false です。

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

  • offlineGoogleAnalytics

    boolean | GoogleAnalyticsInitializeOptions 省略可

    デフォルト値は false です。

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

  • runtimeCaching

    RuntimeCaching[] 省略可

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

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

  • skipWaiting

    ブール値(省略可)

    デフォルト値は false です。

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

  • ソースマップ

    ブール値(省略可)

    デフォルト値は true です。

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

  • swDest

    string(省略可)

    デフォルト値は "service-worker.js" です。

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

InjectManifest

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

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

  • config

    WebpackInjectManifestOptions

プロパティ

default

タイプ

オブジェクト

プロパティ

  • GenerateSW

    クエリ

  • InjectManifest

    クエリ