ワークボックスのレシピ

特にルーティングとキャッシュに関する多くの一般的なパターンは、再利用可能なレシピに標準化できるほど一般的です。workbox-recipes を使用すると、これらの機能を簡単に利用できるパッケージで提供できるため、高度な機能を持つサービス ワーカーをすばやく利用できます。

レシピ

各レシピは、複数の 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 秒未満になるように最適化されています。

このレシピは、デフォルトでネットワーク タイムアウトが 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 は stale-while-revalidate キャッシュ戦略を使用して静的リソース（特に CSS、JavaScript、Web Worker のリクエスト）のリクエストに応答できます。そのため、これらのアセットをキャッシュから迅速に処理して、バックグラウンドで更新できます。

このレシピは、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],
      }),
    ],
  })
);

イメージ キャッシュ

画像キャッシュ レシピを使用すると、サービス ワーカーはキャッシュ ファーストのキャッシュ戦略で画像のリクエストに応答できるため、キャッシュに画像が保存されると、ユーザーが画像を再度リクエストする必要がなくなります。

このレシピでは、デフォルトで最大 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 キャッシュ戦略が使用されます。一方、フォント ファイル自体は変更されないため、キャッシュ ファースト戦略を活用できます。

このレシピでは、デフォルトで最大 30 個のフォント ファイルを 1 年間キャッシュに保存します。すべての構成オプションの一覧については、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,
      }),
    ],
  })
);

クイック使用法

すべてのレシピを組み合わせることで、Service Worker がネットワーク ファーストのキャッシュ戦略でページ リクエストに応答し、CSS、JavaScript、ウェブ ワーカーのリクエストに stale-while-revalidate 戦略で応答し、画像リクエストにキャッシュ ファースト戦略で応答し、Google Fonts を適切にキャッシュに保存して、ページ リクエストのオフライン フォールバックを提供します。これらはすべて、次のコマンドで実行できます。

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

pageCache();

googleFontsCache();

staticResourceCache();

imageCache();

offlineFallback();

型

GoogleFontCacheOptions

プロパティ

  • cachePrefix

    文字列（省略可）

  • maxAgeSeconds

    数値（省略可）

  • maxEntries

    数値（省略可）

ImageCacheOptions

プロパティ

  • cacheName

    文字列（省略可）

  • matchCallback

    RouteMatchCallback オプション

  • maxAgeSeconds

    数値（省略可）

  • maxEntries

    number（省略可）

  • plugins

    WorkboxPlugin[] 省略可

  • warmCache

    string[] 省略可

OfflineFallbackOptions

プロパティ

  • fontFallback

    文字列（省略可）

  • imageFallback

    文字列（省略可）

  • pageFallback

    文字列（省略可）

PageCacheOptions

プロパティ

  • cacheName

    文字列（省略可）

  • matchCallback

    RouteMatchCallback（省略可）

  • networkTimeoutSeconds

    number（省略可）

  • plugins

    WorkboxPlugin[] 省略可

  • warmCache

    string[] 省略可

StaticResourceOptions

プロパティ

WarmStrategyCacheOptions

プロパティ

  • ストラテジー

    戦略

  • URL

    string[]

メソッド

googleFontsCache()

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

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

パラメータ

imageCache()

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

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

パラメータ

offlineFallback()

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

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

パラメータ

pageCache()

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

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

パラメータ

staticResourceCache()

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

[CSS and JavaScript files recipe]の実装https://developers.google.com/web/tools/workbox/guides/common-recipes#cache_css_and_javascript_files

パラメータ

warmStrategyCache()

workbox-recipes.warmStrategyCache(
  options: WarmStrategyCacheOptions,
): void

パラメータ