ワークボックスのビルド

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

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

使用するモード

generateSW

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

generateSW を使用するタイミング

  • ファイルをプリキャッシュしたい。
  • シンプルなランタイム キャッシュ保存のニーズがある。

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

  • 他の Service Worker 機能（Web Push など）を使用したい。
  • 追加のスクリプトをインポートするか、カスタム キャッシュ保存戦略用の追加のロジックを追加する場合。

injectManifest

injectManifest モードでは、プリキャッシュする URL のリストが生成され、そのプリキャッシュ マニフェストが既存のサービス ワーカー ファイルに追加されます。それ以外の場合は、ファイルはそのまま残ります。

injectManifest を使用するタイミング

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

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

  • サイトにサービス ワーカーを追加する最も簡単な方法を探している。

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

タイプ

Omit<GetManifestResult"manifestEntries"
> & object

プロパティ

  • filePaths

    string[]

GeneratePartial

プロパティ

  • babelPresetEnvTargets

    string[] 省略可

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

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

  • cacheId

    文字列（省略可）

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

  • cleanupOutdatedCaches

    boolean（省略可）

    デフォルト値は false です。

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

  • clientsClaim

    boolean（省略可）

    デフォルト値は false です。

    サービス ワーカーがアクティブ化された直後に既存のクライアントの制御を開始するかどうか。

  • directoryIndex

    文字列（省略可）

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

  • disableDevLogs

    boolean（省略可）

    デフォルト値は false です。

  • ignoreURLParametersMatching

    RegExp[] 省略可

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

  • importScripts

    string[] 省略可

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

  • inlineWorkboxRuntime

    boolean（省略可）

    デフォルト値は false です。

    Workbox ライブラリのランタイム コードを最上位のサービス ワーカーに含めるか、サービス ワーカーとともにデプロイする必要がある別のファイルに分割するか。ランタイムを分離しておくと、トップレベルのサービス ワーカーが変更されるたびに 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

    boolean（省略可）

    デフォルト値は false です。

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

  • offlineGoogleAnalytics

    boolean | GoogleAnalyticsInitializeOptions 省略可

    デフォルト値は false です。

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

  • runtimeCaching

    RuntimeCaching[] 省略可

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

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

  • skipWaiting

    boolean（省略可）

    デフォルト値は false です。

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

  • sourcemap

    boolean（省略可）

    デフォルト値は true です。

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

GenerateSWOptions

タイプ

BasePartial & GlobPartial & GeneratePartial & RequiredSWDestPartial & OptionalGlobDirectoryPartial

GetManifestOptions

タイプ

BasePartial & GlobPartial & RequiredGlobDirectoryPartial

GetManifestResult

プロパティ

  • count

    数値

  • manifestEntries

    ManifestEntry[]

  • サイズ

    数値

  • 警告

    string[]

GlobPartial

プロパティ

  • globFollow

    boolean（省略可）

    デフォルト値は true です。

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

  • globIgnores

    string[] 省略可

    デフォルト値は ["**\/node_modules\/**\/*"] です。

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

  • globPatterns

    string[] 省略可

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

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

  • templatedURLs

    オブジェクト 省略可

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

InjectManifestOptions

タイプ

BasePartial & GlobPartial & InjectPartial & RequiredSWDestPartial & RequiredGlobDirectoryPartial

InjectPartial

プロパティ

  • injectionPoint

    文字列（省略可）

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

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

  • swSrc

    文字列

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

ManifestEntry

プロパティ

  • 完全性

    文字列（省略可）

  • リビジョン

    文字列

  • URL

    文字列

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
): Promise<ManifestTransformResult> | ManifestTransformResult

タイプ

関数

パラメータ

  • manifestEntries

    (ManifestEntry & object)[]

    • サイズ

      数値

  • コンパイル

    不明 省略可

戻り値

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() の呼び出しを介して、生成されたサービス ワーカーに含まれます。

  • swDest

    文字列（省略可）

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

    このプラグインによって作成されたサービス ワーカー ファイルのアセット名。

WebpackInjectManifestOptions

タイプ

BasePartial & WebpackPartial & InjectPartial & WebpackInjectManifestPartial

WebpackInjectManifestPartial

プロパティ

  • compileSrc

    boolean（省略可）

    デフォルト値は true です。

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

  • swDest

    文字列（省略可）

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

  • webpackCompilationPlugins

    any[] 省略可

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

WebpackPartial

プロパティ

  • chunks

    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,
): Promise<string>

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

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

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

パラメータ

  • destDirectory

    文字列

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

戻り値

  • Promise<string>

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

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
): Promise<BuildResult>

このメソッドは、指定したオプションに基づいて、プリキャッシュする 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,
): Promise<GetManifestResult>

このメソッドは、指定したオプションに基づいて、プリキャッシュする 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,
): string

パラメータ

  • moduleName

    文字列

  • buildType

    BuildType

戻り値

  • 文字列

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
): Promise<BuildResult>

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

マニフェストは swSrc ファイルに挿入されます。プレースホルダ文字列 injectionPoint は、ファイル内のマニフェストの挿入場所を決定します。

マニフェストが挿入された最終的なサービス ワーカー ファイルは、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: '...',
});

パラメータ

戻り値