ワークボックスのビルド

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

ほとんどのデベロッパーは、generateSW と injectManifest の 2 つのモードを使用します。適切なモードと構成を選択するには、以下の質問への回答を参考にしてください。

使用するモード

generateSW

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

generateSW を使用するケース

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

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

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

injectManifest

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

injectManifest を使用するケース

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

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

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

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

その他のモード

ほとんどのデベロッパーのニーズには、generateSW または injectManifest をおすすめします。ただし、workbox-build では他にも特定のユースケースに適したモードが 1 つあります。

getManifest モード

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

次のように、最も一般的な構成オプションを使用して、ノードベースのビルド スクリプト内で 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

    （文字列|ManifestEntry）[] 省略可

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

  • dontCacheBustURLsMatching

    RegExp（省略可）

    これに一致するアセットは、その URL を使用して一意にバージョニングされていると想定され、事前キャッシュへのデータ入力時に行われる通常の HTTP キャッシュ無効化から除外されます。必須ではありませんが、既存のビルドプロセスで各ファイル名にすでに [hash] 値が挿入されている場合は、その値を検出する RegExp を指定することをおすすめします。そうすることで、事前キャッシュ時に消費される帯域幅が少なくなります。

  • manifestTransforms

    ManifestTransform[] 省略可

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

  • maximumFileSizeToCacheInBytes

    number（省略可）

    デフォルト値は 2097152 です。

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

  • modifyURLPrefix

    オブジェクト 省略可

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

    使用例:

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

BuildResult

タイプ

<GetManifestResult"manifestEntries"
>オブジェクト（&object）を省略します

プロパティ

  • filePaths

    string[]

GeneratePartial

プロパティ

  • babelPresetEnvTargets

    string[] 省略可

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

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

  • cacheId

    string（省略可）

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

  • cleanupOutdatedCaches

    ブール値（省略可）

    デフォルト値は false です。

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

  • clientsClaim

    ブール値（省略可）

    デフォルト値は false です。

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

  • directoryIndex

    string（省略可）

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

  • disableDevLogs

    ブール値（省略可）

    デフォルト値は false です。

  • ignoreURLParametersMatching

    RegExp[]（省略可）

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

  • importScripts

    string[] 省略可

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

  • inlineWorkboxRuntime

    ブール値（省略可）

    デフォルト値は false です。

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

  • モード

    string（省略可）

    デフォルト値は "production" です。

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

  • navigateFallback

    string（省略可）

    デフォルト値は null です。

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

  • navigateFallbackAllowlist

    RegExp[]（省略可）

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

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

  • navigateFallbackDenylist

    RegExp[]（省略可）

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

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

  • navigationPreload

    ブール値（省略可）

    デフォルト値は false です。

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

  • offlineGoogleAnalytics

    boolean|GoogleAnalyticsInitializeOptions optional

    デフォルト値は false です。

    オフライン Google アナリティクスのサポートを含めるかどうかを制御します。true の場合、workbox-google-analytics の initialize() の呼び出しが、生成された 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 ファイルのソースマップを作成するかどうか。

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,css,html}"] です。

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

  • globStrict

    ブール値（省略可）

    デフォルト値は true です。

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

  • templatedURLs

    オブジェクト 省略可

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

InjectManifestOptions

タイプ

BasePartial、GlobPartial、InjectPartial、RequiredSWDestPartial、RequiredGlobDirectoryPartial

InjectPartial

プロパティ

  • injectionPoint

    string（省略可）

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

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

  • swSrc

    文字列

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

ManifestEntry

プロパティ

  • 完全性

    string（省略可）

  • リビジョン

    文字列

  • URL

    文字列

ManifestTransform()

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

タイプ

機能

パラメータ

  • manifestEntries

    （ManifestEntry オブジェクト）[]

    • サイズ

      数値

  • コンパイル

    不明（省略可）

戻り値

ManifestTransformResult

プロパティ

  • マニフェスト

    （ManifestEntry オブジェクト）[]

    • サイズ

      数値

  • 警告

    string[] 省略可

OptionalGlobDirectoryPartial

プロパティ

  • globDirectory

    string（省略可）

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

RequiredGlobDirectoryPartial

プロパティ

  • globDirectory

    文字列

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

RequiredSWDestPartial

プロパティ

  • swDest

    文字列

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

RuntimeCaching

プロパティ

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

  • method

    HTTPMethod 省略可

    デフォルト値は "GET" です。

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

  • オプション

    オブジェクト 省略可

  • urlPattern

    string|RegExp|RouteMatchCallbackRouteMatchCallback

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

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

StrategyName

Enum

"CacheOnly"

WebpackGenerateSWOptions

タイプ

BasePartial、WebpackPartial、GeneratePartial、WebpackGenerateSWPartial

WebpackGenerateSWPartial

プロパティ

  • importScriptsViaChunks

    string[] 省略可

    webpack チャンクの 1 つ以上の名前。これらのチャンクの内容は、importScripts() の呼び出しにより、生成された Service Worker に組み込まれます。

  • swDest

    string（省略可）

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

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

WebpackInjectManifestOptions

タイプ

BasePartial、WebpackPartial、InjectPartial、WebpackInjectManifestPartial

WebpackInjectManifestPartial

プロパティ

  • compileSrc

    ブール値（省略可）

    デフォルト値は true です。

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

  • swDest

    string（省略可）

    このプラグインによって作成される Service Worker ファイルのアセット名。省略すると、名前は swSrc 名に基づきます。

  • webpackCompilationPlugins

    any[] 省略可

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

WebpackPartial

プロパティ

  • チャンク

    string[] 省略可

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

  • 対象外にする

    (string|RegExp|function)[] optional

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

  • excludeChunks

    string[] 省略可

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

  • 含める

    (string|RegExp|function)[] optional

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

  • モード

    string（省略可）

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

Methods

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
)

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

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

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

パラメータ

  • destDirectory

    文字列

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

戻り値

  • Promise<文字列>

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

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
)

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

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

事前キャッシュ マニフェストと追加構成に基づいて、すぐに使用できる 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: '...',
});

パラメータ

戻り値