Bermigrasi dari Workbox v2 ke v3

Panduan ini berfokus pada perubahan yang dapat menyebabkan gangguan yang diperkenalkan di Workbox v3, dengan contoh perubahan yang perlu Anda buat saat mengupgrade dari penyiapan Workbox v2.

Jika saat ini Anda menggunakan kombinasi sw-precache/sw-toolbox lama, dan ingin beralih ke Workbox untuk pertama kalinya, berikut panduan migrasi yang berbeda yang akan membantu.

Latar belakang v3

Rilis v3 Workbox mewakili pemfaktoran ulang yang signifikan terhadap codebase yang ada. Tujuan secara keseluruhan adalah:

  • Minimalkan ukuran Workbox. Jumlah kode runtime pekerja layanan yang didownload dan dieksekusi telah dikurangi. Daripada menyertakan semua orang dalam paket monolitik, hanya kode untuk fitur tertentu yang Anda gunakan yang akan diimpor saat runtime.
  • Workbox memiliki CDN. Kami menyediakan hosting CDN berbasis Google Cloud Storage yang didukung penuh sebagai opsi kanonis untuk mengakses library runtime Workbox, sehingga memudahkan Anda untuk mulai menggunakan Workbox.
  • Proses Debug dan Log yang Lebih Baik. Pengalaman proses debug dan logging telah jauh lebih baik. Log debug diaktifkan secara default setiap kali Workbox digunakan dari asal localhost dan semua logging serta pernyataan dihilangkan dari build produksi. Contoh logging debug yang ditawarkan oleh Workbox v3.
  • Plugin webpack yang lebih baik. workbox-webpack-plugin terintegrasi lebih erat dengan proses build webpack, sehingga memungkinkan kasus penggunaan tanpa konfigurasi saat Anda ingin melakukan precache semua aset di pipeline build.

Untuk mencapai tujuan ini, dan membersihkan beberapa aspek antarmuka sebelumnya yang terasa canggung atau menyebabkan anti-pola, diperlukan untuk memperkenalkan sejumlah perubahan yang dapat menyebabkan gangguan dalam rilis v3.

Perubahan yang Dapat Menyebabkan Gangguan

Konfigurasi Build

Perubahan berikut memengaruhi perilaku semua alat build kita (workbox-build, workbox-cli, workbox-webpack-plugin), yang memiliki kumpulan opsi konfigurasi umum.

  • Nama pengendali 'fastest' sebelumnya valid, dan diperlakukan sebagai alias untuk 'staleWhileRevalidate', saat mengonfigurasi runtimeCaching. Atribut ini tidak lagi valid, dan developer harus beralih menggunakan 'staleWhileRevalidate' secara langsung.
  • Beberapa nama properti runtimeCaching.options telah diperbarui, dan validasi parameter tambahan diterapkan yang akan menyebabkan build gagal jika konfigurasi yang tidak valid digunakan. Lihat dokumentasi untuk runtimeCaching guna melihat daftar opsi yang saat ini didukung.

sinkronisasi latar belakang-workbox

  • Parameter konfigurasi maxRetentionTime kini ditafsirkan sebagai jumlah menit, bukan jumlah milidetik.
  • Kini ada string yang diperlukan, yang mewakili nama antrean, yang harus diteruskan sebagai parameter pertama saat membuat Plugin atau class mandiri. (Sebelumnya diteruskan sebagai properti opsi.) Lihat dokumentasi untuk platform API yang telah diupdate.

workbox-broadcast-cache-update

  • Kini ada string yang diperlukan, yang mewakili nama saluran, dan harus diteruskan sebagai parameter pertama saat membuat Plugin atau class mandiri.

Misalnya, di v2, Anda akan melakukan inisialisasi class Plugin seperti berikut:

new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
  channelName: 'cache-updates',
  headersToCheck: ['etag'],
});

Penggunaan yang setara di v3 adalah:

new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});

Lihat dokumentasi untuk platform API yang telah diupdate.

build-workbox

  • Secara default, pencocokan pola glob kini akan dilakukan dengan opsi follow: true (yang akan mengikuti symlink) dan strict: true (yang kurang toleran terhadap error "tidak biasa"). Anda dapat menonaktifkan salah satunya dan kembali ke perilaku sebelumnya dengan menyetel globFollow: false dan/atau globStrict: false dalam konfigurasi build Anda.
  • Semua fungsi dalam workbox-build menampilkan properti tambahan, warnings, dalam respons yang ditampilkan. Beberapa skenario yang dianggap sebagai error fatal di v2 kini diizinkan, tetapi dilaporkan melalui warnings, yang merupakan array string.

Di v2, Anda dapat memanggil generateSW seperti:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size}) => console.log(`Precached ${count} files, totaling ${size} bytes.`))
  .catch((error) => console.error(`Something went wrong: ${error}`));

Meskipun Anda dapat menggunakan kode yang sama di v3, sebaiknya periksa semua warnings dan catat:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size, warnings}) => {
    for (const warning of warnings) {
      console.warn(warning);
    }
    console.log(`Precached ${count} files, totalling ${size} bytes.`);
  })
  .catch((error) => console.error(`Something went wrong: ${error}`));
  • Developer yang menulis fungsi ManifestTransform kustom mereka sendiri di v2 harus menampilkan array manifes dalam objek (yaitu, bukan return manifestArray;, Anda harus menggunakan return {manifest: manifestArray};).mHal ini memungkinkan plugin Anda menyertakan properti warnings opsional, yang harus berupa array string yang berisi informasi peringatan non-fatal.

Jika Anda menulis ManifestTransform kustom di v2, maka kode seperti:

const cdnTransform = manifestEntries => {
  return manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
};

memiliki v3 yang setara dengan:

const cdnTransform = manifestEntries => {
  const manifest = manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
  return {manifest, warnings: []};
};
  • Fungsi getFileManifestEntries() telah diganti namanya menjadi getManifest(), dan promise yang ditampilkan sekarang menyertakan informasi tambahan tentang URL yang telah di-precache.

Kode seperti berikut di v2:

const manifestEntries = await workboxBuild.getFileManifestEntries({...});

dapat ditulis ulang di v3 sebagai:

const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.
  • Fungsi generateFileManifest() telah dihapus. Sebaiknya developer memanggil getManifest(), dan menggunakan responsnya untuk menulis data ke disk dalam format yang sesuai.

workbox-cache-masa berlaku

  • API plugin tetap sama, yang merupakan mode yang pada akhirnya akan digunakan oleh sebagian besar developer. Namun, ada perubahan API signifikan yang memengaruhi developer yang menggunakannya sebagai class mandiri. Lihat dokumentasi untuk platform API yang telah diupdate.

workbox-cli

Developer dapat menjalankan CLI dengan flag --help untuk sekumpulan lengkap parameter yang didukung.

  • Dukungan untuk alias workbox-cli untuk skrip biner telah dihapus. Sekarang biner hanya dapat diakses sebagai workbox.
  • Perintah v2 generate:sw dan inject:manifest telah diganti namanya menjadi generateSW dan injectManifest di v3.
  • Di v2, file konfigurasi default (digunakan jika file tidak disediakan secara eksplisit) diasumsikan sebagai workbox-cli-config.js di direktori saat ini. Di v3, sebesar workbox-config.js.

Secara keseluruhan, ini berarti bahwa di v2:

$ workbox inject:manifest

akan menjalankan proses build "inject manifest", menggunakan pembacaan konfigurasi dari workbox-cli-config.js, dan dalam v3:

$ workbox injectManifest

akan melakukan hal yang sama, tetapi membaca konfigurasi dari workbox-config.js.

precaching kotak kerja

  • Metode precache() sebelumnya menjalankan modifikasi cache dan menyiapkan perutean untuk menampilkan entri yang di-cache. Sekarang, precache() hanya mengubah entri cache, dan metode baru, addRoute(), telah diekspos untuk mendaftarkan rute guna menayangkan respons yang di-cache tersebut. Developer yang menginginkan fungsi dua dalam satu sebelumnya dapat beralih ke panggilan precacheAndRoute().
  • Beberapa opsi yang sebelumnya dikonfigurasi melalui konstruktor WorkboxSW kini diteruskan sebagai parameter options di workbox.precaching.precacheAndRoute([...], options). Setelan default untuk opsi tersebut, jika tidak dikonfigurasi, akan tercantum dalam dokumen referensi.
  • Secara default, URL yang tidak memiliki ekstensi file akan otomatis diperiksa kecocokannya dengan entri cache yang berisi ekstensi .html. Misalnya, jika permintaan dibuat untuk /path/to/index (yang tidak di-precache) dan ada entri yang di-precache untuk /path/to/index.html, entri yang di-cache tersebut akan digunakan. Developer dapat menonaktifkan perilaku baru ini dengan menetapkan {cleanUrls: false} saat meneruskan opsi ke workbox.precaching.precacheAndRoute().
  • workbox-broadcast-update tidak akan lagi dikonfigurasi secara otomatis untuk mengumumkan pembaruan cache bagi aset yang di-cache.

Kode berikut di v2:

const workboxSW = new self.WorkboxSW({
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
  precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);

memiliki v3 yang setara dengan:

workbox.precaching.addPlugins([
    new workbox.broadcastUpdate.Plugin('precache-updates')
]);

workbox.precaching.precacheAndRoute([...], {
  cleanUrls: false,
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
});

pemilihan rute kotak kerja

  • Developer yang sebelumnya menggunakan workbox-routing melalui namespace workbox.router.* objek WorkboxSW perlu beralih ke namespace baru, workbox.routing.*.
  • Rute sekarang dievaluasi dalam urutan pertama-terdaftar-menang. Ini adalah urutan berlawanan dari evaluasi Route yang digunakan dalam v2, dengan Route yang terakhir didaftarkan akan lebih diutamakan.
  • Class ExpressRoute dan dukungan untuk karakter pengganti "gaya ekspres" telah dihapus. Hal ini mengurangi ukuran workbox-routing secara signifikan. String yang digunakan sebagai parameter pertama untuk workbox.routing.registerRoute() kini akan diperlakukan sebagai pencocokan persis. Karakter pengganti atau kecocokan sebagian harus ditangani oleh RegExp—menggunakan RegExp yang cocok dengan sebagian atau semua URL permintaan dapat memicu rute.
  • Metode helper addFetchListener() dari class Router telah dihapus. Developer dapat menambahkan pengendali fetch mereka sendiri secara eksplisit, atau menggunakan antarmuka yang disediakan oleh workbox.routing, yang secara implisit akan membuat pengendali fetch untuk mereka.
  • Metode registerRoutes() dan unregisterRoutes() telah dihapus. Versi metode tersebut yang beroperasi di satu Route tidak berubah, dan developer yang perlu mendaftarkan atau membatalkan pendaftaran beberapa rute sekaligus harus melakukan serangkaian panggilan ke registerRoute() atau unregisterRoute().

Kode berikut di v2:

const workboxSW = new self.WorkboxSW();

workboxSW.router.registerRoute(
  '/path/with/.*/wildcard/',
  workboxSW.strategies.staleWhileRevalidate()
);

workboxSW.router.registerRoute(
  new RegExp('^https://example.com/'),
  workboxSW.strategies.networkFirst()
);

memiliki v3 yang setara dengan:

workbox.routing.registerRoute(
  new RegExp('^https://example.com/'),
  workbox.strategies.networkFirst()
);

workbox.routing.registerRoute(
  new RegExp('^/path/with/.*/wildcard'),
  workbox.strategies.staleWhileRevalidate()
);

strategi-workbox (sebelumnya dikenal sebagai workbox-runtime-caching)

  • Modul workbox-runtime-caching kini secara resmi dikenal sebagai workbox-strategies, dan telah dipublikasikan pada npm dengan nama barunya.
  • Menggunakan masa berlaku cache dalam strategi tanpa memberikan nama cache tidak lagi valid. Di v2, hal ini memungkinkan:
workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

Hal ini akan menyebabkan entri yang kedaluwarsa dalam cache default, yang tidak diharapkan. Pada v3, nama cache diperlukan:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});
  • Metode siklus proses cacheWillMatch telah diganti namanya menjadi cachedResponseWillBeUsed. Hal ini seharusnya tidak menjadi perubahan yang terlihat bagi developer, kecuali jika mereka menulis plugin mereka sendiri yang bereaksi terhadap cacheWillMatch.
  • Sintaksis untuk menentukan plugin saat mengonfigurasi strategi telah berubah. Setiap plugin harus dicantumkan secara eksplisit di properti plugins pada konfigurasi strategi.

Kode berikut di v2:

const workboxSW = new self.WorkboxSW();

const networkFirstStrategy = workboxSW.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  cacheExpiration: {
    maxEntries: 50,
  },
  cacheableResponse: {
    statuses: [0, 200],
  },
});

memiliki v3 yang setara dengan:

const networkFirstStrategy = workbox.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  plugins: [
    new workbox.expiration.Plugin({maxEntries: 50}),
    new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
  ],
});

Anda dapat mempelajari lebih lanjut di panduan "Menggunakan Plugin".

workbox-sw

  • Di balik layar, workbox-sw telah ditulis ulang menjadi antarmuka "loader" ringan, yang menggunakan beberapa konfigurasi dasar dan bertanggung jawab untuk menarik modul lain yang diperlukan saat runtime. Daripada membuat instance baru dari class WorkboxSW, developer akan berinteraksi dengan instance yang ada yang ditampilkan secara otomatis dalam namespace global.

Sebelumnya di v2:

importScripts('<path to workbox-sw>/importScripts/workbox-sw.prod.v2.1.3.js');

const workbox = new WorkboxSW({
  skipWaiting: true,
  clientsClaim: true,
  // etc.
});

workbox.router.registerRoute(...);

Di v3, Anda hanya perlu mengimpor skrip workbox-sw.js, dan instance yang siap digunakan akan otomatis tersedia di namespace global sebagai workbox:

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

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);
  • skipWaiting dan clientsClaim bukan lagi opsi yang diteruskan ke konstruktor WorkboxSW. Sebagai gantinya, keduanya telah diubah ke metode workbox.clientsClaim() dan workbox.skipWaiting().
  • Opsi handleFetch yang sebelumnya didukung di konstruktor v2 tidak lagi didukung di v3. Developer yang memerlukan fungsi serupa untuk menguji pekerja layanan mereka tanpa pengendali pengambilan yang dipanggil dapat menggunakan opsi "Abaikan untuk jaringan" yang tersedia di Developer Tools Chrome.
Opsi Abaikan untuk Jaringan di Chrome DevTools.

workbox-webpack-plugin

Plugin ini telah banyak ditulis ulang, dan dalam banyak kasus, dapat digunakan dalam mode "konfigurasi nol". Lihat dokumentasi untuk platform API yang telah diupdate.

  • API ini sekarang mengekspos dua class, yaitu GenerateSW dan InjectManifest. Hal ini membuat peralihan antara mode menjadi eksplisit, vs. perilaku v2 dengan perilaku berubah berdasarkan keberadaan swSrc.
  • Secara default, aset di pipeline kompilasi webpack akan di-pracache, dan tidak perlu lagi mengonfigurasi globPatterns. Satu-satunya alasan untuk terus menggunakan globPatterns adalah jika Anda perlu melakukan precache aset yang tidak disertakan dalam build webpack Anda. Secara umum, saat bermigrasi ke plugin v3, Anda harus memulai dengan menghapus semua konfigurasi berbasis glob sebelumnya, dan hanya menambahkannya kembali jika Anda secara khusus membutuhkannya.

Mendapatkan bantuan

Kami memperkirakan sebagian besar migrasi akan mudah dilakukan. Jika Anda mengalami masalah yang tidak tercakup dalam panduan ini, beri tahu kami dengan membuka masalah di GitHub.