ワークボックスのビルド

workbox-build モジュールはノードベースのビルドプロセスに統合され、サービス ワーカー全体を生成することも、既存のサービス ワーカー内で使用できるプリキャッシュ アセットのリストを生成することもできます。

ほとんどのデベロッパーが使用する 2 つのモードは、generateSW と injectManifest です。次の質問に答えることで、使用する適切なモードと構成を選択できます。

使用するモード

generateSW

generateSW モードでは、構成オプションでカスタマイズされたサービス ワーカー ファイルが作成され、ディスクに書き出されます。

generateSW を使用するタイミング

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

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

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

injectManifest

injectManifest モードでは、事前キャッシュする URL のリストが生成され、その事前キャッシュ マニフェストが既存の Service Worker ファイルに追加されます。ファイルが変更されていない場合は、ファイルはそのままになります。

injectManifest を使用するタイミング

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

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

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

generateSW モード

次のように、最も一般的な構成オプションを使用して、ノードベースのビルド スクリプト内で generateSW モードを使用できます。

// Inside of build.js:
const {generateSW} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while generating a service worker:',
      warnings.join('\n')
    );
  }

  console.log(`Generated a service worker, which will precache ${count} files, totaling ${size} bytes.`);
});

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

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

injectManifest モード

次のように、最も一般的な構成オプションを使用して、ノードベースのビルド スクリプト内で injectManifest モードを使用できます。

// Inside of build.js:
const {injectManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while injecting the manifest:',
      warnings.join('\n')
    );
  }

  console.log(`Injected a manifest which will precache ${count} files, totaling ${size} bytes.`);
});

これにより、構成で取得されたファイルに基づいてプリキャッシュ マニフェストが作成され、既存のサービス ワーカー ファイルに挿入されます。

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

その他のモード

ほとんどのデベロッパーのニーズには generateSW または injectManifest が適していると思われます。ただし、workbox-build でサポートされているもう 1 つのモードは、特定のユースケースに適している場合があります。

getManifest モード

これは概念的には injectManifest モードに似ていますが、マニフェストをソース サービス ワーカー ファイルに追加するのではなく、マニフェスト エントリの配列と、エントリ数と合計サイズに関する情報を返します。

次のように、最も一般的な構成オプションを使用して、ノードベースのビルド スクリプト内で injectManifest モードを使用できます。

// Inside of build.js:
const {getManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
}).then(({manifestEntries, count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while getting the manifest:',
      warnings.join('\n')
    );
  }

  // Do something with the manifestEntries, and potentially log count and size.
});

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

型

BasePartial

プロパティ

  • additionalManifestEntries

    （string | ManifestEntry）[] 省略可

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

  • dontCacheBustURLsMatching

    RegExp（省略可）

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

  • manifestTransforms

    ManifestTransform[] 省略可

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

  • maximumFileSizeToCacheInBytes

    number（省略可）

    デフォルト値は 2097152 です。

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

  • modifyURLPrefix

    オブジェクト（省略可）

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

    使用例:

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

BuildResult

タイプ

<GetManifestResult"manifestEntries"
> とオブジェクトを省略

プロパティ

  • filePaths

    string[]

GeneratePartial

プロパティ

  • babelPresetEnvTargets

    string[] 省略可

    デフォルト値は: ["chrome >= 56"]

    サービス ワーカー バンドルをトランスパイルするときに babel-preset-env に渡すターゲット。

  • cacheId

    文字列 省略可

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

  • cleanupOutdatedCaches

    ブール値（省略可）

    デフォルト値は false です。

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

  • clientsClaim

    ブール値（省略可）

    デフォルト値は false です。

    Service Worker がアクティベートされた直後に、既存のクライアントの制御を開始するかどうか。

  • directoryIndex

    文字列 省略可

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

  • disableDevLogs

    ブール値（省略可）

    デフォルト値は false です。

  • ignoreURLParametersMatching

    RegExp[] 省略可

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

  • importScripts

    string[] 省略可

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

  • inlineWorkboxRuntime

    ブール値（省略可）

    デフォルト値は false です。

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

  • モード

    文字列 省略可

    デフォルト値は「production」です。

    「production」に設定すると、デバッグ情報を除外した最適化されたサービス ワーカー バンドルが生成されます。ここで明示的に設定されていない場合、process.env.NODE_ENV 値が使用され、それが失敗すると 'production' にフォールバックします。

  • 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() をトリガーできるようになります。

  • sourcemap

    ブール値（省略可）

    デフォルト値は true です。

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

GenerateSWOptions

タイプ

BasePartial、GlobPartial、GeneratePartial、RequiredSWDestPartial、OptionalGlobDirectoryPartial

GetManifestOptions

タイプ

BasePartial、GlobPartial、RequiredGlobDirectoryPartial

GetManifestResult

プロパティ

  • count

    数値

  • manifestEntries

    ManifestEntry[]

  • サイズ

    数値

  • 警告

    string[]

GlobPartial

プロパティ

  • globFollow

    ブール値（省略可）

    デフォルト値は true です。

    プリキャッシュ マニフェストの生成時にシンボリック リンクに従うかどうかを決定します。詳細については、glob のドキュメントで follow の定義をご覧ください。

  • globIgnores

    string[] 省略可

    デフォルト値は: ["**\/node_modules\/**\/*"]

    プリキャッシュ マニフェストの生成時に常に除外するファイルに一致する一連のパターン。詳細については、glob のドキュメントで ignore の定義をご覧ください。

  • globPatterns

    string[] 省略可

    デフォルト値は: ["**\/*.{js,wasm,css,html}"]

    これらのパターンのいずれかに一致するファイルは、プリキャッシュ マニフェストに含まれます。詳細については、glob の概要をご覧ください。

  • globStrict

    ブール値（省略可）

    デフォルト値は true です。

    true の場合、プリキャッシュ マニフェストの生成時にディレクトリの読み取りエラーが発生すると、ビルドが失敗します。false の場合、問題のあるディレクトリはスキップされます。詳細については、glob のドキュメントで strict の定義をご覧ください。

  • templatedURLs

    オブジェクト（省略可）

    URL がサーバーサイド ロジックに基づいてレンダリングされる場合、その内容は複数のファイルまたは他の一意の文字列値に依存する可能性があります。このオブジェクトのキーは、サーバー側でレンダリングされた URL です。値が文字列の配列の場合、それらは glob パターンとして解釈され、パターンに一致するファイルのコンテンツを使用して URL が一意にバージョニングされます。1 つの文字列で使用すると、特定の URL に対して生成した一意のバージョニング情報として解釈されます。

InjectManifestOptions

タイプ

BasePartial、GlobPartial、InjectPartial、RequiredSWDestPartial、RequiredGlobDirectoryPartial

InjectPartial

プロパティ

  • injectionPoint

    文字列 省略可

    デフォルト値は「self.__WB_MANIFEST」です。"self.__WB_MANIFEST"

    swSrc ファイル内で検索する文字列。見つかった場合、生成されたプリキャッシュ マニフェストに置き換えられます。

  • swSrc

    文字列

    ビルドプロセス中に読み取られるサービス ワーカー ファイルのパスとファイル名（現在の作業ディレクトリを基準とする相対パス）。

ManifestEntry

プロパティ

  • 完全性

    文字列 省略可

  • リビジョン

    文字列

  • URL

    文字列

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
)

タイプ

関数

パラメータ

  • manifestEntries

    (ManifestEntry & object)[]

    • サイズ

      数値

  • compilation

    不明 省略可

戻り値

ManifestTransformResult

プロパティ

  • マニフェスト

    (ManifestEntry & object)[]

    • サイズ

      数値

  • 警告

    string[] 省略可

OptionalGlobDirectoryPartial

プロパティ

  • globDirectory

    文字列 省略可

    globPatterns と照合するローカル ディレクトリ。パスは現在のディレクトリを基準とする相対パスです。

RequiredGlobDirectoryPartial

プロパティ

  • globDirectory

    文字列

    globPatterns と照合するローカル ディレクトリ。パスは現在のディレクトリを基準とする相対パスです。

RequiredSWDestPartial

プロパティ

  • swDest

    文字列

    ビルドプロセスによって作成されるサービス ワーカー ファイルのパスとファイル名（現在の作業ディレクトリを基準とする相対パス）。末尾は「.js」にする必要があります。

RuntimeCaching

プロパティ

  • これにより、ランタイム ルートがレスポンスを生成する方法が決まります。組み込みの workbox-strategies のいずれかを使用するには、その名前（'NetworkFirst' など）を指定します。または、カスタム レスポンス ロジックを含む workbox-core.RouteHandler コールバック関数にすることもできます。

  • method

    HTTPMethod（省略可）

    デフォルト値は「GET」です。

    照合する HTTP メソッド。通常は、'POST'、'PUT'、または他のタイプのリクエストと明示的に一致させる必要がある場合を除き、デフォルト値 'GET' で十分です。

  • オプション

    オブジェクト（省略可）

  • urlPattern

    string | RegExp | RouteMatchCallback

    この一致条件により、事前キャッシュに保存された URL のいずれにも一致しないリクエストに対して、構成済みのハンドラがレスポンスを生成するかどうかが決まります。複数の RuntimeCaching ルートが定義されている場合は、urlPattern が一致する最初のルートがレスポンスを返します。

    この値は、workbox-routing.registerRoute に渡される最初のパラメータに直接マッピングされます。最大限の柔軟性を確保するには、workbox-core.RouteMatchCallback 関数を使用することをおすすめします。

StrategyName

列挙型

「CacheFirst」

「CacheOnly」

「NetworkFirst」

「NetworkOnly」

「StaleWhileRevalidate」

WebpackGenerateSWOptions

タイプ

BasePartial、WebpackPartial、GeneratePartial、WebpackGenerateSWPartial

WebpackGenerateSWPartial

プロパティ

  • importScriptsViaChunks

    string[] 省略可

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

  • swDest

    文字列 省略可

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

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

WebpackInjectManifestOptions

タイプ

BasePartial、WebpackPartial、InjectPartial、WebpackInjectManifestPartial

WebpackInjectManifestPartial

プロパティ

  • compileSrc

    ブール値（省略可）

    デフォルト値は true です。

    true（デフォルト）の場合、swSrc ファイルは webpack によってコンパイルされます。false の場合、コンパイルは行われません（webpackCompilationPlugins は使用できません）。マニフェストを JSON ファイルなどに挿入する場合は、false に設定します。

  • swDest

    文字列 省略可

    このプラグインによって作成されるサービス ワーカー ファイルのアセット名。省略すると、名前は swSrc 名に基づいて設定されます。

  • webpackCompilationPlugins

    any[] 省略可

    swSrc 入力ファイルをコンパイルするときに使用されるオプションの webpack プラグイン。compileSrc が true の場合にのみ有効です。

WebpackPartial

プロパティ

  • チャンク

    string[] 省略可

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

  • 除外

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

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

  • excludeChunks

    string[] 省略可

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

  • 含む

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

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

  • モード

    文字列 省略可

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

メソッド

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
)

これにより、Workbox で使用される一連のランタイム ライブラリがローカル ディレクトリにコピーされます。このディレクトリは、Service Worker ファイルと一緒にデプロイする必要があります。

これらのローカルコピーをデプロイする代わりに、公式の CDN URL から Workbox を使用することもできます。

このメソッドは、Workbox の CDN コピーを使用したくない workbox-build.injectManifest を使用するデベロッパー向けに公開されています。workbox-build.generateSW を使用するデベロッパーは、このメソッドを明示的に呼び出す必要はありません。

パラメータ

  • destDirectory

    文字列

    ライブラリの新しいディレクトリが作成される親ディレクトリのパス。

戻り値

  • Promise<string>

    新しく作成されたディレクトリの名前。

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
)

このメソッドは、指定されたオプションに基づいて、プリキャッシュする URL のリスト（プリキャッシュ マニフェスト）を作成します。

また、使用すべき runtimeCaching ルールなど、Service Worker の動作を構成する追加オプションも受け取ります。

プリキャッシュ マニフェストと追加の構成に基づいて、すぐに使用できるサービス ワーカー ファイルを swDest にディスクに書き込みます。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
});

パラメータ

戻り値

getManifest()

workbox-build.getManifest(
  config: GetManifestOptions,
)

このメソッドは、指定したオプションに基づいて、プリキャッシュする URL のリスト（プリキャッシュ マニフェスト）と、エントリの数とサイズの詳細を返します。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, manifestEntries, size, warnings} = await getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
});

パラメータ

戻り値

getModuleURL()

workbox-build.getModuleURL(
  moduleName: string,
  buildType: BuildType,
)

パラメータ

  • moduleName

    文字列

  • buildType

    BuildType

戻り値

  • 文字列

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
)

このメソッドは、指定されたオプションに基づいて、プリキャッシュする URL のリスト（プリキャッシュ マニフェスト）を作成します。

マニフェストは swSrc ファイルに挿入され、プレースホルダ文字列 injectionPoint によって、マニフェストを配置するファイル内の場所が決まります。

マニフェストが挿入された最終的な Service Worker ファイルが、swDest にディスクに書き込まれます。

この方法では、swSrc ファイルはコンパイルまたはバンドルされません。マニフェストの挿入のみが処理されます。

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
});

パラメータ

戻り値