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 menunjukkan pemfaktoran ulang yang signifikan dari codebase yang ada. Tujuan umumnya adalah:

  • Minimalkan ukuran Workbox. Jumlah kode runtime pekerja layanan yang didownload dan dieksekusi telah dikurangi. Alih-alih mengikutsertakan semua orang ke 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 untuk menyiapkan dan menjalankan Workbox.
  • Proses Debug dan Log yang Lebih Baik. Pengalaman proses debug dan logging telah jauh ditingkatkan. Log debug diaktifkan secara default setiap kali Workbox digunakan dari asal localhost dan semua logging serta pernyataan dihapus dari build produksi. Contoh logging debug yang ditawarkan oleh Workbox v3.
  • Plugin webpack ditingkatkan. workbox-webpack-plugin terintegrasi secara lebih dekat dengan proses build webpack, sehingga memungkinkan kasus penggunaan tanpa konfigurasi saat Anda ingin melakukan pra-cache semua aset dalam pipeline build.

Mencapai sasaran ini dan membersihkan beberapa aspek antarmuka sebelumnya yang terasa janggal atau menimbulkan antipola, mengharuskan adanya sejumlah perubahan yang dapat menyebabkan gangguan dalam rilis v3.

Perubahan yang Dapat Menyebabkan Gangguan

Build Configuration

Perubahan berikut memengaruhi perilaku semua alat build kami (workbox-build, workbox-cli, workbox-webpack-plugin), yang memiliki sekumpulan opsi konfigurasi yang sama.

  • Nama pengendali 'fastest' sebelumnya valid, dan diperlakukan sebagai alias untuk 'staleWhileRevalidate', saat mengonfigurasi runtimeCaching. Kode ini sudah tidak 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 mengetahui daftar opsi yang saat ini didukung.

workbox-background-sync

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

workbox-broadcast-cache-update

  • Sekarang ada string wajib, yang mewakili nama saluran, yang 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 diperbarui.

workbox-build

  • Secara default, pencocokan pola glob kini akan dilakukan dengan opsi follow: true (yang akan mengikuti symlink) dan strict: true (yang tidak terlalu toleran terhadap error "tidak biasa"). Anda dapat menonaktifkan salah satunya dan kembali ke perilaku sebelumnya dengan menyetel globFollow: false dan/atau globStrict: false di konfigurasi build Anda.
  • Semua fungsi di workbox-build menampilkan properti tambahan, warnings, dalam respons yang ditampilkannya. Beberapa skenario yang diperlakukan 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 warnings apa pun dan catat dalam log:

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 perlu menampilkan array manifes dalam objek (yaitu, alih-alih 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, 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 padanan v3 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 kini menyertakan informasi tambahan tentang URL yang di-pra-cache.

Kode seperti berikut di v2:

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

dapat ditulis ulang dalam 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. Developer dianjurkan untuk memanggil getManifest(), dan menggunakan responsnya untuk menulis data ke disk dalam format yang sesuai.

workbox-cache-expiration

  • 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 diperbarui.

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. Biner ini sekarang 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 tidak disediakan secara eksplisit) dianggap sebagai workbox-cli-config.js dalam direktori saat ini. Di v3, parameternya adalah workbox-config.js.

Secara keseluruhan, ini berarti bahwa dalam v2:

$ workbox inject:manifest

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

$ workbox injectManifest

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

{i>workbox-precaching<i}

  • Metode precache() sebelumnya melakukan modifikasi cache dan menyiapkan pemilihan rute untuk menayangkan entri yang di-cache. Sekarang, precache() hanya mengubah entri cache, dan metode baru, addRoute(), telah diekspos untuk mendaftarkan rute guna menyalurkan respons yang di-cache tersebut. Developer yang menginginkan fungsi dua dalam satu versi sebelumnya dapat beralih ke memanggil precacheAndRoute().
  • Beberapa opsi yang sebelumnya dikonfigurasi melalui konstruktor WorkboxSW kini diteruskan sebagai parameter options di workbox.precaching.precacheAndRoute([...], options). Default untuk opsi tersebut, jika tidak dikonfigurasi, 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-pra-cache) dan ada entri pra-cache untuk /path/to/index.html, entri pra-cache tersebut akan digunakan. Developer dapat menonaktifkan perilaku baru ini dengan menyetel {cleanUrls: false} saat meneruskan opsi ke workbox.precaching.precacheAndRoute().
  • workbox-broadcast-update tidak akan lagi dikonfigurasi secara otomatis guna mengumumkan update cache untuk aset yang di-pra-cache.

Kode berikut di v2:

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

memiliki padanan v3 dengan:

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

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

perutean workbox

  • Developer yang sebelumnya menggunakan workbox-routing melalui namespace workbox.router.* objek WorkboxSW harus beralih ke namespace baru, workbox.routing.*.
  • Rute kini dievaluasi dalam urutan first-registered-wins. Ini adalah urutan kebalikan dari evaluasi Route yang digunakan dalam v2, tempat Route yang terakhir didaftarkan akan diprioritaskan.
  • Class ExpressRoute, dan dukungan untuk "Express-style" karakter pengganti telah dihapus. Tindakan ini akan mengurangi ukuran workbox-routing secara signifikan. String yang digunakan sebagai parameter pertama untuk workbox.routing.registerRoute() sekarang akan diperlakukan sebagai kecocokan persis. Kecocokan parsial atau karakter pengganti harus ditangani oleh RegExp—menggunakan RegExp yang cocok dengan sebagian atau seluruh URL permintaan dapat memicu rute.
  • Metode bantuan 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 pada 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 padanan v3 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 menyediakan nama cache juga tidak lagi valid. Di v2, hal ini dimungkinkan:
workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

Hal ini akan menyebabkan entri kedaluwarsa di cache default, yang tidak diharapkan. Di v3, nama cache wajib diisi:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});
  • Metode siklus proses cacheWillMatch telah diganti namanya menjadi cachedResponseWillBeUsed. Perubahan ini tidak akan 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 padanan v3 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 "Menggunakan Plugin" kami.

workbox-sw

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

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. Namun, keduanya telah diubah menjadi 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 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 ditulis ulang secara substansial, dan dalam banyak kasus, dapat digunakan dalam "konfigurasi nol" mode. Lihat dokumentasi untuk platform API yang diperbarui.

  • API sekarang mengekspos dua class, GenerateSW dan InjectManifest. Hal ini membuat peralihan antarmode menjadi eksplisit, vs. perilaku v2 dengan perilaku yang berubah berdasarkan keberadaan swSrc.
  • Secara default, aset di pipeline kompilasi webpack akan di-pra-cache, dan tidak perlu lagi mengonfigurasi globPatterns. Satu-satunya alasan untuk terus menggunakan globPatterns adalah jika Anda perlu melakukan pra-cache 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 secara khusus memerlukannya.

Mendapatkan bantuan

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