Workboxを使うと何ができるのか？Workboxの各packageのまとめ #PWA

Workboxとは

Workboxとは、Service Workerを簡単に使えるように、各種APIを抽象化したモジュールを集めたものです。

Workbox is a set of modules that simplify common service worker routing and caching.

Service Workerを使うには、ネットワークリクエスト、キャッシュ戦略、キャッシュ管理、プリキャッシュなど必要な知識が多く、それらを抽象化することで取り組みやすく、かつ柔軟にカスタマイズもできるようになっています。

Workboxを手軽に使う方法としては、generateSW や injectManifest を使う方法があります。

またその他にもWorkboxの各モジュールを使用する方法があり、その場合にどういうときにどれを使えばいいのかを整理したくなったため、調べてまとめてみました。

Workbox Modules

上記ページには、Service Worker Packagesとして以下のようなパッケージが挙げられています。
それぞれの機能を調べながら、Workboxでできることをまとめます。

2022年6月現在、Workboxの最新バージョンはv6.5.2です

ここからはworkboxのドキュメントを引用しながらまとめていきます。

workbox-routing

ネットワークリクエスト時に、Service Workerが間に入って処理をすることができますが、このルーティング設定ができます。

ルーティング条件とhandlerを設定することで、特定のルーティングの時にService Workerがキャッシュをブラウザに返すなどといった設定や、エラー発生時のハンドリングなどを設定できます。

registerRoute(new RegExp('/styles/.*\\.css'), handlerCb);

workbox-strategies

キャッシュ戦略を設定できます。

Cache only / Network only / Cache first / Network first / Stale-while-revalidate などの詳細はこちらをご覧ください。

workbox-routingと合わせて使うことで、ルーティングによってキャッシュ戦略を変更できます。

registerRoute(
  ({url}) => url.pathname.startsWith('/social-timeline/'),
  new NetworkFirst()
);

また、カスタムストラテジーとして、Strategyクラスを継承した独自の戦略を定義することもできます。

workbox-precaching

プリキャッシュの設定ができます。
Service Workerには precaching と runtime caching という2つの概念があり、このうちService Workerインストール時に事前キャッシュする、 precache を指しています。
それぞれの説明はこちらをご覧ください。

Service Workerのinstallイベントの最中に、アセットの事前ダウンロードとキャッシュを行い、その際に古くなったキャッシュの削除なども行えます。
事前にダウンロードしておくことで、次回以降のリクエスト発生時に、キャッシュファーストで応答ができます。

precacheAndRoute([
  {url: '/index.html', revision: '383676'},
  {url: '/styles/app.0c9a31.css', revision: null},
  {url: '/scripts/app.0d5770.js', revision: null},
  // ... other entries ...
]);

workbox-expiration

キャッシュの期間や保存する数の管理ができます。

workbox-strategiesと組み合わせて、各キャッシュ戦略ごとの設定ができます。

registerRoute(
  ({request}) => request.destination === 'image',
  new CacheFirst({
    cacheName: 'image-cache',
    plugins: [
      new ExpirationPlugin({
        maxEntries: 20,
        maxAgeSeconds: 24 * 60 * 60,
      }),
    ],
  })
);

workbox-core

各モジュールが依存するロジックが含まれています。
デバッグや型定義の使用などで使います。

console.log(cacheNames.precache);
console.log(cacheNames.runtime);
console.log(cacheNames.googleAnalytics);

また、キャッシュ名の変更もできます。

setCacheNameDetails({
  prefix: 'my-app',
  suffix: 'v1',
  precache: 'install-time',
  runtime: 'run-time',
  googleAnalytics: 'ga',
});

// Will print 'my-app-install-time-v1'
console.log(cacheNames.precache);

workbox-background-sync

バックグラウンド同期を使って、オフラインなどでネットワークリクエストが失敗した場合、接続ができたタイミングでリクエストを再送信できます。

キューを作成し、一定時間以内のものをバックグラウンド同期するといったものが設定できます。

const bgSyncPlugin = new BackgroundSyncPlugin('myQueueName', {
  maxRetentionTime: 24 * 60, // Retry for max of 24 Hours (specified in minutes)
});

registerRoute(
  /\/api\/.*\/*.json/,
  new NetworkOnly({
    plugins: [bgSyncPlugin],
  }),
  'POST'
);

workbox-broadcast-update

キャッシュの更新が検知されたときに、通知します。
一般的に、StaleWhileRevalidateとともに使われます。

registerRoute(
  ({url}) => url.pathname.startsWith('/api/'),
  new StaleWhileRevalidate({
    plugins: [new BroadcastUpdatePlugin()],
  })
);

workbox-cacheable-response

キャッシュをするかどうかを、レスポンスのステータスコードか、レスポンスヘッダーに基づきルールを設定できます。

registerRoute(
  ({url}) => url.pathname.startsWith('/path/to/api/'),
  new StaleWhileRevalidate({
    cacheName: 'api-cache',
    plugins: [
      new CacheableResponsePlugin({
        statuses: [200, 404],
        headers: {
          'X-Is-Cacheable': 'true',
        },
      }),
    ],
  })
);

workbox-google-analytics

オフライン時のユーザーデータをGoogle Analyticsに送信するために、一時的にIndexedDBに保存し、ネットワーク接続がされた時に再試行できます。

import * as googleAnalytics from 'workbox-google-analytics';

googleAnalytics.initialize();

カスタムディメンションを使って、オンラインとオフラインを分けて分析することもできます。

workbox-navigation-preload

navigation preloadを使うことで、Service Workerがアクティブになる前にリクエストをすることができます。

Service Workerの起動に時間がかかると、その間リクエストが遅延してしまいますが、これを防ぐことができます。

navigationPreload.enable();

workbox-range-requests

ビデオファイルの再生などで、キャッシュされたファイルの一部のみを返したい時に使えます。

registerRoute(
  ({url}) => url.pathname.endsWith('.mp4'),
  new CacheFirst({
    plugins: [
      new RangeRequestsPlugin(),
    ],
  });
);

workbox-recipes

よく使われるパターンをレシピとして使うことができます。

offlineFallback: オフラインで、かつキャッシュが存在しない場合にフォールバックとして表示する設定
warmStrategyCache: Service Workerのinstallフェーズに特定のキャッシュ戦略でキャッシュのウォームアップ
pageCache: ページキャッシュ
staticResourceCache: CSS, JavaScript, Web WorkerのリクエストをStaleWhileRevalidateでのキャッシュ
imageCache: imageのキャッシュ
googleFontsCache: GoogleFontsの@font-face定義、フォントファイルのキャッシュ

Workboxを使うと何ができるのか？Workboxの各packageのまとめ

Workboxとは

Workbox Modules

参考