Bermigrasi dari sw-precache atau sw-toolbox

Developer yang sebelumnya telah menggunakan sw-precache dan/atau sw-toolbox memiliki jalur upgrade yang mudah ke rangkaian library Workbox. Upgrade ke Workbox akan memberikan pengalaman pekerja layanan modern yang dapat diperluas dengan proses debug dan ergonomi developer yang lebih baik.

Perubahan pada konfigurasi yang ada

Jika menggunakan sw-precache yang dikonfigurasi dengan salah satu opsi berikut, Anda harus mempertimbangkan perubahan berikut saat bermigrasi ke Workbox.

Opsi yang diganti namanya

Parameter konfigurasi dynamicUrlToDependencies telah diganti namanya menjadi templatedURLs.

Parameter konfigurasi staticFileGlobs telah diganti namanya menjadi globPatterns.

Parameter konfigurasi runtimeCaching menggunakan sekumpulan opsi yang diperbarui, yang sesuai dengan nama yang digunakan dalam modul Workbox yang mendasarinya. Untuk menggambarkan apa yang telah diganti namanya, konfigurasi sw-precache ini:

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

setara dengan konfigurasi Workbox ini:

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,
    },
  },
}],

Opsi yang tidak digunakan lagi

Rute karakter pengganti bergaya Express tidak lagi didukung. Jika Anda menggunakan rute karakter pengganti gaya Express dalam konfigurasi runtimeCaching atau langsung di sw-toolbox, migrasikan ke rute ekspresi reguler yang setara saat menggunakan Workbox.

Migrasi sw-precache

Dari CLI sw-precache ke workbox-cli

Developer yang menggunakan antarmuka command line sw-precache, baik yang menjalankan perintah secara manual maupun sebagai bagian dari proses build berbasis npm scripts, akan menggunakan modul workbox-cli sebagai cara termudah untuk melakukan migrasi. Menginstal workbox-cli akan memberi Anda akses ke biner yang disebut workbox.

Meskipun CLI sw-precache didukung untuk melakukan konfigurasi melalui flag command line atau file konfigurasi, CLI workbox mewajibkan semua opsi konfigurasi disediakan dalam file konfigurasi, menggunakan CommonJS module.exports.

CLI workbox mendukung sejumlah mode berbeda. (Gunakan workbox --help untuk melihat semuanya.) Namun, mode yang paling cocok dengan fungsi sw-precache adalah generateSW. Jadi panggilan ke

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

dapat dinyatakan sebagai

$ workbox generateSW workbox-config.js

Dari modul node sw-precache ke modul node workbox-build

Developer yang menggunakan node API untuk sw-precache, baik sebagai bagian dari alur kerja gulp/Grunt atau hanya dalam skrip build node kustom, dapat bermigrasi dengan beralih ke modul node workbox-build.

Fungsi generateSW() modul workbox-build paling cocok dengan fungsi write() modul sw-precache. Satu perbedaan utamanya adalah generateSW() selalu menampilkan Promise, sedangkan fungsi write() lama mendukung callback dan antarmuka berbasis Promise.

Penggunaan gulp di sepanjang garis

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

dapat diubah menjadi

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

Dari plugin sw-precache-webpack-plugin ke plugin webpack Workbox

Developer yang menggunakan sw-precache-webpack-plugin sebagai bagian dari proses build webpack mereka dapat bermigrasi dengan beralih ke class GenerateSW dalam modul workbox-webpack-plugin.

workbox-webpack-plugin terintegrasi langsung dengan proses build webpack dan "mengetahui" semua aset yang dihasilkan oleh kompilasi tertentu. Ini berarti bahwa, untuk banyak kasus penggunaan, Anda dapat mengandalkan perilaku default workbox-webpack-plugin tanpa konfigurasi tambahan, dan mendapatkan pekerja layanan yang setara dengan yang disediakan sw-precache-webpack-plugin.

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

dapat diubah menjadi

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

migrasi sw-toolbox

Bermigrasi dari sw-toolbox buatan tangan ke workbox-sw

Jika Anda menggunakan sw-toolbox secara langsung (bukan menggunakannya secara implisit melalui opsi runtimeCaching sw-precache), migrasi ke Workbox memerlukan beberapa penyesuaian manual untuk mendapatkan perilaku yang setara. Untuk konteks selengkapnya, baca dokumentasi untuk modul workbox-routing dan workbox-strategies dapat membantu memberikan konteks yang lebih lengkap.

Berikut beberapa cuplikan kode untuk membantu memandu migrasi. Kode sw-toolbox ini:

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;

setara dengan kode Workbox ini:

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());

Mendapatkan bantuan

Kami berharap sebagian besar migrasi ke Workbox mudah dilakukan. Jika Anda mengalami masalah yang tidak dibahas dalam panduan ini, beri tahu kami dengan membuka masalah di GitHub.