このページは Cloud Translation API によって翻訳されました。

sw-precache または sw-toolbox から移行する

以前に sw-precache や sw-toolbox を使用していたデベロッパーの場合、Workbox のライブラリファミリーに簡単にアップグレードできます。Workbox にアップグレードすると、デバッグとデベロッパーの使い勝手が改善された、最新の拡張可能なサービスワーカーエクスペリエンスが提供されます。

既存の構成の変更

次のいずれかのオプションで構成された sw-precache を使用している場合は、Workbox に移行する際に次の変更を考慮する必要があります。

名前が変更されたオプション

dynamicUrlToDependencies 構成パラメータの名前が templatedURLs に変更されました。

staticFileGlobs 構成パラメータの名前が globPatterns に変更されました。

runtimeCaching 構成パラメータは、基盤となる Workbox モジュールで使用される名前に対応する、更新されたオプションのセットを受け取ります。名前が変更された内容を示す sw-precache 構成は次のとおりです。

runtimeCaching: [{
  urlPattern: /api/,
  handler: 'fastest',
  options: {
    cache: {
      name: 'my-api-cache',
      maxEntries: 5,
      maxAgeSeconds: 60,
    },
  },
}],

は、次の Workbox 構成と同等です。

runtimeCaching: [{
  urlPattern: /api/,
  // 'fastest' is now 'StaleWhileRevalidate'
  handler: 'StaleWhileRevalidate',
  options: {
    // options.cache.name is now options.cacheName
    cacheName: 'my-api-cache',
    // options.cache is now options.expiration
    expiration: {
      maxEntries: 5,
      maxAgeSeconds: 60,
    },
  },
}],

サポートが終了したオプション

エクスプレススタイルのワイルドカードルートはサポートされなくなりました。runtimeCaching 構成または sw-toolbox で直接 Express スタイルのワイルドカードルートを使用していた場合は、Workbox を使用するときに同等の正規表現ルートに移行します。

sw-precache の移行

sw-precache CLI から workbox-cli に移動する

sw-precache コマンドラインインターフェースを使用するデベロッパー（コマンドを手動で実行する場合や、npm scripts ベースのビルドプロセスの一部として実行する場合）は、workbox-cli モジュールを使用するのが最も簡単な移行方法です。workbox-cli をインストールすると、workbox というバイナリにアクセスできるようになります。

sw-precache CLI は、コマンドラインフラグまたは構成ファイルによる構成をサポートしていますが、workbox CLI では、CommonJS module.exports を使用して、すべての構成オプションを構成ファイルで指定する必要があります。

workbox CLI は、さまざまなモードをサポートしています。（workbox --help を使用してすべて表示できます）。ただし、sw-precache の機能に最も近いモードは generateSW です。つまり、

$ sw-precache --config='sw-precache-config.js'

は次のように表すことができます。

$ workbox generateSW workbox-config.js

sw-precache ノードモジュールから workbox-build ノードモジュールへ

gulp/Grunt ワークフローの一部として、またはカスタム node ビルドスクリプト内で sw-precache の node API を使用しているデベロッパーは、workbox-build node モジュールに切り替えることで移行できます。

workbox-build モジュールの generateSW() 関数は、sw-precache モジュールの write() 関数と非常によく似ています。主な違いの 1 つは、generateSW() は常に Promise を返すのに対し、古い write() 関数はコールバックと Promise ベースのインターフェースの両方をサポートしていたことです。

gulp の使用例:

const swPrecache = require('sw-precache');
gulp.task('generate-service-worker', function () {
  return swPrecache.write('service-worker.js', {
    // Config options.
  });
});

に変更できます。

const workboxBuild = require('workbox-build');
gulp.task('generate-service-worker', function () {
  return workboxBuild.generateSW({
    // Config options.
  });
});

sw-precache-webpack-plugin から Workbox webpack プラグインへ

webpack ビルドプロセスの一部として sw-precache-webpack-plugin を使用しているデベロッパーは、workbox-webpack-plugin モジュール内の GenerateSW クラスに切り替えることで移行できます。

workbox-webpack-plugin は webpack ビルドプロセスと直接統合され、特定のコンパイルによって生成されたすべてのアセットを「認識」します。つまり、多くのユースケースでは、追加の構成なしで workbox-webpack-plugin のデフォルトの動作に依存し、sw-precache-webpack-plugin が提供するものと同等の Service Worker を取得できます。

const SWPrecacheWebpackPlugin = require('sw-precache-webpack-plugin');
const webpackConfig = {
  // ...
  plugins: [
    new SWPrecacheWebpackPlugin({
      dontCacheBustUrlsMatching: /\.\w{8}\./,
      filename: 'service-worker.js',
    }),
  ],
};

に変更できます。

const {GenerateSW} = require('workbox-webpack-plugin');
const webpackConfig = {
  // ...
  plugins: [
    new GenerateSW({
      // Config options, if needed.
    }),
  ],
};

sw-toolbox の移行

手動で作成した sw-toolbox から workbox-sw に移行する

sw-toolbox を直接使用していた場合（sw-precache の runtimeCaching オプションを介して暗黙的に使用していた場合ではない）、Workbox に移行するには、同等の動作を実現するために手動で調整する必要があります。詳細については、workbox-routing モジュールと workbox-strategies モジュールのドキュメントをご覧ください。

移行に役立つコードスニペットをいくつか紹介します。この sw-toolbox コードの目的は次のとおりです。

importScripts('path/to/sw-toolbox.js');

// Set up a route that matches HTTP 'GET' requests.
toolbox.router.get(
  // Match any URL that contains 'ytimg.com', regardless of
  // where in the URL that match occurs.
  /\.ytimg\.com\//,

  // Apply a cache-first strategy to anything that matches.
  toolbox.cacheFirst,

  {
    // Configure a custom cache name and expiration policy.
    cache: {
      name: 'youtube-thumbnails',
      maxEntries: 10,
      maxAgeSeconds: 30,
    },
  }
);

// Set a default network-first strategy to use when
// there is no explicit matching route:
toolbox.router.default = toolbox.networkFirst;

は、次の Workbox コードと同等です。

importScripts('path/to/workbox-sw.js');

workbox.routing.registerRoute(
  // Match any URL that contains 'ytimg.com'.
  // Unlike in sw-toolbox, in Workbox, a RegExp that matches
  // a cross-origin URL needs to include the initial 'https://'
  // as part of the match.
  new RegExp('^https://.*.ytimg.com'),

  // Apply a cache-first strategy to anything that matches.
  new workbox.strategies.CacheFirst({
    // Configuration options are passed in to the strategy.
    cacheName: 'youtube-thumbnails',
    plugins: [
      new workbox.expiration.ExpirationPlugin({
        maxEntries: 10,
        maxAgeSeconds: 30,
      }),
      // In Workbox, you must explicitly opt-in to caching
      // responses with a status of 0 when using the
      // cache-first strategy.
      new workbox.cacheableResponse.CacheableResponsePlugin({
        statuses: [0, 200],
      }),
    ],
  })
);

// Set a default network-first strategy to use when
// there is no explicit matching route:
workbox.routing.setDefaultHandler(new workbox.strategies.NetworkFirst());

困ったときは

Workbox への移行はほとんどが簡単な作業になるはずです。このガイドに記載されていない問題が発生した場合は、GitHub で問題を報告してください。