ワークボックスのレシピ

特にルーティングキャッシュに関する多くの一般的なパターンは、再利用可能なレシピに標準化できるほど一般的です。workbox-recipes は、これらを使いやすいパッケージで提供し、高機能な Service Worker をすぐに使い始めることができます。

レシピ

各レシピは、いくつかの Workbox モジュールを組み合わせたもので、よく使用されるパターンにバンドルされています。以下のレシピでは、このモジュールを使用するときに使用するレシピと、内部で使用する同等のパターン(自分で記述する場合)を示します。

オフライン フォールバック

オフライン フォールバック レシピを使用すると、たとえばユーザーがオフラインでキャッシュ ヒットがない場合など、3 つのいずれかでルーティング エラーが発生した場合に、Service Worker はウェブページ、画像、フォントを提供できます。Workbox Recipes のバージョン 6.1.0 では、プレキャッシュを使用してこれらのアイテムをキャッシュに保存する要件が削除されました。下位互換性を確保するため、独自のキャッシュを試す前に、まずプレキャッシュ内のアイテムを検索します。

デフォルトでは、このレシピは代替ページが offline.html であり、画像やフォントの代替がないことを前提としています。すべての構成オプションの一覧については、オフライン フォールバック オプションをご覧ください。

オフライン フォールバックは、指定されたリクエストに一致するルートがある場合にのみ適用されます。オフラインのフォールバック レシピを単独で使用する場合は、ルートを自分で作成する必要があります。最も簡単な方法は、以下に示すように、setDefaultHandler() メソッドを使用して、NetworkOnly 戦略をすべてのリクエストに適用するルートを作成することです。その他のレシピ(ページ キャッシュ静的リソース キャッシュイメージ キャッシュなど)では、それぞれのキャッシュのルートを設定します。オフライン フォールバックといずれかのレシピの両方を使用する場合、setDefaultHandler() は必要ありません。

レシピ

import {offlineFallback} from 'workbox-recipes';
import {setDefaultHandler} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

setDefaultHandler(new NetworkOnly());

offlineFallback();

パターン

import {setCatchHandler, setDefaultHandler} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

const pageFallback = 'offline.html';
const imageFallback = false;
const fontFallback = false;

setDefaultHandler(new NetworkOnly());

self.addEventListener('install', event => {
  const files = [pageFallback];
  if (imageFallback) {
    files.push(imageFallback);
  }
  if (fontFallback) {
    files.push(fontFallback);
  }

  event.waitUntil(
    self.caches
      .open('workbox-offline-fallbacks')
      .then(cache => cache.addAll(files))
  );
});

const handler = async options => {
  const dest = options.request.destination;
  const cache = await self.caches.open('workbox-offline-fallbacks');

  if (dest === 'document') {
    return (await cache.match(pageFallback)) || Response.error();
  }

  if (dest === 'image' && imageFallback !== false) {
    return (await cache.match(imageFallback)) || Response.error();
  }

  if (dest === 'font' && fontFallback !== false) {
    return (await cache.match(fontFallback)) || Response.error();
  }

  return Response.error();
};

setCatchHandler(handler);

ウォーム戦略キャッシュ

ウォーム戦略のキャッシュ レシピを使用すると、Service Worker の install フェーズで指定された URL をキャッシュに読み込み、指定された戦略のオプションでキャッシュに保存できます。キャッシュする URL がわかっている場合や、ルートのキャッシュをウォームしたい場合など、インストール中に URL をキャッシュしたい場合には、この機能をプレキャッシュの代わりに使用できます。

すべての構成オプションの一覧については、ウォーム戦略のキャッシュ オプションをご覧ください。

レシピ

import {warmStrategyCache} from 'workbox-recipes';
import {CacheFirst} from 'workbox-strategies';

// This can be any strategy, CacheFirst used as an example.
const strategy = new CacheFirst();
const urls = ['/offline.html'];

warmStrategyCache({urls, strategy});

パターン

import {CacheFirst} from 'workbox-strategies';
// This can be any strategy, CacheFirst used as an example.
const strategy = new CacheFirst();
const urls = ['/offline.html'];

self.addEventListener('install', event => {
  // handleAll returns two promises, the second resolves after all items have been added to cache.
  const done = urls.map(
    path =>
      strategy.handleAll({
        event,
        request: new Request(path),
      })[1]
  );

  event.waitUntil(Promise.all(done));
});

ページ キャッシュ

ページ キャッシュ レシピを使用すると、Service Worker はネットワーク ファーストのキャッシュ戦略を使用して(URL ナビゲーションから)HTML ページのリクエストに応答できます。これは、キャッシュ フォールバックが 4.0 秒未満の Largest Contentful Paint スコアに十分な速さで到着するように最適化されているのが理想的です。

デフォルトでは、このレシピはネットワーク タイムアウトを 3 秒と想定し、warmCache オプションを介してキャッシュ ウォーミングをサポートしています。すべての構成オプションの一覧については、ページ キャッシュ オプションをご覧ください。

レシピ

import {pageCache} from 'workbox-recipes';

pageCache();

パターン

import {registerRoute} from 'workbox-routing';
import {NetworkFirst} from 'workbox-strategies';
import {CacheableResponsePlugin} from 'workbox-cacheable-response';

const cacheName = 'pages';
const matchCallback = ({request}) => request.mode === 'navigate';
const networkTimeoutSeconds = 3;

registerRoute(
  matchCallback,
  new NetworkFirst({
    networkTimeoutSeconds,
    cacheName,
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
    ],
  })
);

静的リソース キャッシュ

静的リソース キャッシュ レシピを使用すると、Service Worker は静的リソース(具体的には CSS、JavaScript、Web Worker のリクエスト)のリクエストに stale-while-revalidate キャッシュ戦略で応答できるため、これらのアセットをキャッシュから迅速に提供してバックグラウンドで更新できます。

このレシピは、warmCache オプションを介してキャッシュ ウォーミングをサポートしています。すべての構成オプションの一覧については、静的リソース キャッシュ オプションをご覧ください。

レシピ

import {staticResourceCache} from 'workbox-recipes';

staticResourceCache();

パターン

import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';
import {CacheableResponsePlugin} from 'workbox-cacheable-response';

const cacheName = 'static-resources';
const matchCallback = ({request}) =>
  // CSS
  request.destination === 'style' ||
  // JavaScript
  request.destination === 'script' ||
  // Web Workers
  request.destination === 'worker';

registerRoute(
  matchCallback,
  new StaleWhileRevalidate({
    cacheName,
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
    ],
  })
);

画像キャッシュ

画像キャッシュ レシピを使用すると、Service Worker はキャッシュ ファーストのキャッシュ戦略で画像のリクエストに応答できます。これにより、画像がキャッシュに格納されると、ユーザーは別のリクエストを行う必要がなくなります。

このレシピはデフォルトで、最大 60 個の画像(それぞれ 30 日間)をキャッシュに保存し、warmCache オプションを介してキャッシュ ウォーミングをサポートしています。すべての構成オプションの一覧については、イメージ キャッシュ オプションをご覧ください。

レシピ

import {imageCache} from 'workbox-recipes';

imageCache();

パターン

import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
import {CacheableResponsePlugin} from 'workbox-cacheable-response';
import {ExpirationPlugin} from 'workbox-expiration';

const cacheName = 'images';
const matchCallback = ({request}) => request.destination === 'image';
const maxAgeSeconds = 30 * 24 * 60 * 60;
const maxEntries = 60;

registerRoute(
  matchCallback,
  new CacheFirst({
    cacheName,
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
      new ExpirationPlugin({
        maxEntries,
        maxAgeSeconds,
      }),
    ],
  })
);

Google Fonts のキャッシュ

Google Fonts レシピでは、Google Fonts リクエストの 2 つの部分がキャッシュに保存されます。

  • フォント ファイルにリンクする @font-face 定義を含むスタイルシート。
  • 変更された静的なフォント ファイル。

スタイルシートは頻繁に変更される可能性があるため、stale-while-revalidate キャッシュ方式が使用されます。一方、フォント ファイル自体は変更されないため、キャッシュ優先の方法を利用できます。

このレシピはデフォルトで、それぞれ 1 年間に最大 30 個のフォント ファイルをキャッシュに保存します。すべての設定オプションのリストについては、Google Fonts のキャッシュ オプションをご覧ください。

レシピ

import {googleFontsCache} from 'workbox-recipes';

googleFontsCache();

パターン

import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';
import {CacheFirst} from 'workbox-strategies';
import {CacheableResponsePlugin} from 'workbox-cacheable-response';
import {ExpirationPlugin} from 'workbox-expiration';

const sheetCacheName = 'google-fonts-stylesheets';
const fontCacheName = 'google-fonts-webfonts';
const maxAgeSeconds = 60 * 60 * 24 * 365;
const maxEntries = 30;

registerRoute(
  ({url}) => url.origin === 'https://fonts.googleapis.com',
  new StaleWhileRevalidate({
    cacheName: sheetCacheName,
  })
);

// Cache the underlying font files with a cache-first strategy for 1 year.
registerRoute(
  ({url}) => url.origin === 'https://fonts.gstatic.com',
  new CacheFirst({
    cacheName: fontCacheName,
    plugins: [
      new CacheableResponsePlugin({
        statuses: [0, 200],
      }),
      new ExpirationPlugin({
        maxAgeSeconds,
        maxEntries,
      }),
    ],
  })
);

クイック使用

すべてのレシピを組み合わせることで、ネットワーク ファーストのキャッシュ戦略でページ リクエストに応答し、stale-while-revalidate 戦略で CSS、JavaScript、Web Worker のリクエストに応答し、キャッシュ優先戦略で画像リクエストに応答し、Google Fonts を適切にキャッシュに保存し、ページ リクエストに対するオフライン フォールバックを提供する Service Worker が作成されます。これはすべて、以下を使用して実行できます。

import {
  pageCache,
  imageCache,
  staticResourceCache,
  googleFontsCache,
  offlineFallback,
} from 'workbox-recipes';

pageCache();

googleFontsCache();

staticResourceCache();

imageCache();

offlineFallback();

GoogleFontCacheOptions

プロパティ

  • cachePrefix

    string(省略可)

  • maxAgeSeconds

    number(省略可)

  • maxEntries

    number(省略可)

ImageCacheOptions

プロパティ

  • cacheName

    string(省略可)

  • matchCallback
  • maxAgeSeconds

    number(省略可)

  • maxEntries

    number(省略可)

  • プラグイン

    WorkboxPlugin[] 省略可

  • warmCache

    string[] 省略可

OfflineFallbackOptions

プロパティ

  • fontFallback

    string(省略可)

  • imageFallback

    string(省略可)

  • pageFallback

    string(省略可)

PageCacheOptions

プロパティ

  • cacheName

    string(省略可)

  • matchCallback
  • networkTimeoutSeconds

    number(省略可)

  • プラグイン

    WorkboxPlugin[] 省略可

  • warmCache

    string[] 省略可

StaticResourceOptions

プロパティ

WarmStrategyCacheOptions

プロパティ

  • ストラテジー
  • urls

    string[]

Methods

googleFontsCache()

workbox-recipes.googleFontsCache(
  options?: GoogleFontCacheOptions,
)

[Google fonts]https://developers.google.com/web/tools/workbox/guides/common-recipes#google_fonts キャッシュ レシピの実装

パラメータ

imageCache()

workbox-recipes.imageCache(
  options?: ImageCacheOptions,
)

[画像キャッシュ レシピ]https://developers.google.com/web/tools/workbox/guides/common-recipes#caching_images の実装

パラメータ

offlineFallback()

workbox-recipes.offlineFallback(
  options?: OfflineFallbackOptions,
)

[包括的なフォールバック レシピ]https://developers.google.com/web/tools/workbox/guides/advanced-recipes#comprehensive_fallbacks の実装。プリキャッシュ インジェクションには必ずフォールバックを含めてください

パラメータ

pageCache()

workbox-recipes.pageCache(
  options?: PageCacheOptions,
)

ネットワーク タイムアウトを設定したページ キャッシュ レシピの実装

パラメータ

staticResourceCache()

workbox-recipes.staticResourceCache(
  options?: StaticResourceOptions,
)

[CSS ファイルと JavaScript ファイルのレシピ]の実装https://developers.google.com/web/tools/workbox/guides/common-recipes#cache_css_and_javascript_files

パラメータ

warmStrategyCache()

workbox-recipes.warmStrategyCache(
  options: WarmStrategyCacheOptions,
)

パラメータ