Bermigrasi dari Workbox v5 ke v6

Panduan ini berfokus pada perubahan yang dapat menyebabkan gangguan yang diperkenalkan di Workbox v6, dengan contoh perubahan yang perlu Anda lakukan saat mengupgrade dari Workbox v5.

Perubahan yang Dapat Menyebabkan Gangguan

workbox-core

Metode skipWaiting() di workbox-core tidak akan lagi menambahkan pengendali install dan setara dengan hanya memanggil self.skipWaiting().

Mulai sekarang, gunakan self.skipWaiting() karena skipWaiting() kemungkinan akan dihapus di Workbox v7.

workbox-precaching

  • Dokumen HTML lintas origin untuk URL yang sesuai dengan pengalihan HTTP tidak dapat lagi digunakan untuk memenuhi permintaan navigasi dengan workbox-precaching. Skenario ini umumnya tidak umum.
  • Parameter kueri URL fbclid kini diabaikan oleh workbox-precaching saat mencari respons yang di-precaching untuk permintaan tertentu.
  • Konstruktor PrecacheController kini menggunakan objek dengan properti tertentu sebagai parameternya, bukan string. Objek ini mendukung properti berikut: cacheName (memiliki tujuan yang sama dengan string yang diteruskan ke konstruktor di v5), plugins (menggantikan metode addPlugins() dari v5), dan fallbackToNetwork (menggantikan opsi serupa yang diteruskan ke createHandler() dan `createHandlerBoundToURL() di v5).
  • Metode install() dan activate() dari PrecacheController kini menggunakan tepat satu parameter, yang harus ditetapkan ke InstallEvent atau ActivateEvent yang sesuai.
  • Metode addRoute() telah dihapus dari PrecacheController. Sebagai gantinya, class PrecacheRoute baru dapat digunakan untuk membuat rute yang kemudian dapat Anda daftarkan.
  • Metode precacheAndRoute() telah dihapus dari PrecacheController. (Metode ini masih ada sebagai metode helper statis yang diekspor oleh modul workbox-precaching.) Fitur ini dihapus karena PrecacheRoute dapat digunakan sebagai gantinya.
  • Metode createMatchCalback() telah dihapus dari PrecacheController. PrecacheRoute baru dapat digunakan sebagai gantinya.
  • Metode createHandler() telah dihapus dari PrecacheController. Properti strategy dari objek PrecacheController dapat digunakan untuk menangani permintaan.
  • Ekspor statis createHandler() telah dihapus dari modul workbox-precaching. Sebagai gantinya, developer harus membuat instance PrecacheController dan menggunakan properti strategy-nya.
  • Rute yang terdaftar dengan precacheAndRoute() kini menjadi rute "nyata" yang menggunakan class Router workbox-routing di balik layar. Hal ini dapat menyebabkan urutan evaluasi rute yang berbeda jika Anda menyisipkan panggilan ke registerRoute() dan precacheAndRoute().

workbox-routing

Metode setDefaultHandler() kini menggunakan parameter kedua opsional yang sesuai dengan metode HTTP yang diterapkan, dengan default 'GET'.

  • Jika Anda menggunakan setDefaultHandler() dan semua permintaan Anda adalah GET, Anda tidak perlu melakukan perubahan apa pun.
  • Jika Anda memiliki permintaan yang bukan GET (POST, PUT, dll.), setDefaultHandler() tidak akan lagi menyebabkan permintaan tersebut cocok.

Konfigurasi Build

Opsi mode untuk mode getManifest dan injectManifest di workbox-build dan workbox-cli tidak dimaksudkan untuk didukung dan telah dihapus. Hal ini tidak berlaku untuk workbox-webpack-plugin, yang mendukung mode di plugin InjectManifest-nya.

Alat Build Memerlukan Node.js v10 atau yang Lebih Tinggi

Node.js versi sebelum v10 tidak lagi didukung untuk workbox-webpack-plugin, workbox-build, atau workbox-cli. Jika Anda menjalankan Node.js versi sebelum v8, update runtime Anda ke versi yang didukung.

Peningkatan Baru

workbox-strategies

Workbox v6 memperkenalkan cara baru bagi developer pihak ketiga untuk menentukan strategi Workbox mereka sendiri. Hal ini memastikan developer pihak ketiga memiliki kemampuan untuk memperluas Workbox dengan cara yang sepenuhnya memenuhi kebutuhan mereka.

Class dasar Strategi baru

Di v6, semua class strategi Workbox harus memperluas class dasar Strategy baru. Semua strategi bawaan telah ditulis ulang untuk mendukung hal ini.

Class dasar Strategy bertanggung jawab atas dua hal utama:

  • Memanggil callback siklus proses plugin yang umum untuk semua pengendali strategi (misalnya, saat dimulai, merespons, dan berakhir).
  • Membuat instance "pengendali", yang dapat mengelola status untuk setiap permintaan individual yang ditangani strategi.

Class "handler" baru

Sebelumnya, kami memiliki modul internal bernama fetchWrapper dan cacheWrapper, yang (seperti namanya) menggabungkan berbagai API pengambilan dan cache dengan hook ke dalam siklus prosesnya. Ini adalah mekanisme yang saat ini memungkinkan plugin berfungsi, tetapi tidak diekspos kepada developer.

Class "handler" baru, StrategyHandler, akan mengekspos metode ini sehingga strategi kustom dapat memanggil fetch() atau cacheMatch() dan membuat plugin apa pun yang ditambahkan ke instance strategi dipanggil secara otomatis.

Class ini juga memungkinkan developer menambahkan callback siklus proses kustom mereka sendiri yang mungkin spesifik untuk strategi mereka, dan callback tersebut akan "langsung berfungsi" dengan antarmuka plugin yang ada.

Status siklus proses plugin baru

Di Workbox v5, plugin bersifat stateless. Artinya, jika permintaan untuk /index.html memicu callback requestWillFetch dan cachedResponseWillBeUsed, kedua callback tersebut tidak dapat berkomunikasi satu sama lain atau bahkan mengetahui bahwa keduanya dipicu oleh permintaan yang sama.

Di v6, semua callback plugin juga akan meneruskan objek state baru. Objek status ini akan unik untuk objek plugin tertentu dan pemanggilan strategi tertentu (yaitu panggilan ke handle()). Hal ini memungkinkan developer menulis plugin yang satu callback-nya dapat melakukan sesuatu secara bersyarat berdasarkan tindakan callback lain dalam plugin yang sama (misalnya, menghitung delta waktu antara menjalankan requestWillFetch dan fetchDidSucceed atau fetchDidFail).

Callback siklus proses plugin baru

Callback siklus proses plugin baru telah ditambahkan untuk memungkinkan developer memanfaatkan sepenuhnya status siklus proses plugin:

  • handlerWillStart: dipanggil sebelum logika pengendali mulai berjalan. Callback ini dapat digunakan untuk menetapkan status pengendali awal (misalnya, mencatat waktu mulai).
  • handlerWillRespond: dipanggil sebelum metode handle() strategi menampilkan respons. Callback ini dapat digunakan untuk mengubah respons tersebut sebelum menampilkannya ke pengendali rute atau logika kustom lainnya.
  • handlerDidRespond: dipanggil setelah metode handle() strategi menampilkan respons. Callback ini dapat digunakan untuk mencatat detail respons akhir, misalnya setelah perubahan yang dibuat oleh plugin lain.
  • handlerDidComplete: dipanggil setelah semua promise perpanjangan masa aktif yang ditambahkan ke peristiwa dari pemanggilan strategi ini diselesaikan. Callback ini dapat digunakan untuk melaporkan data apa pun yang perlu menunggu hingga pengendali selesai untuk menghitung (misalnya, status cache ditemukan, latensi cache, latensi jaringan).
  • handlerDidError: dipanggil jika pengendali tidak dapat memberikan respons yang valid dari sumber mana pun. Callback ini dapat digunakan untuk menyediakan konten "penggantian" sebagai alternatif untuk error jaringan.

Developer yang menerapkan strategi kustom mereka sendiri tidak perlu khawatir untuk memanggil callback ini sendiri; semuanya ditangani oleh class dasar Strategy baru.

Jenis TypeScript yang lebih akurat untuk pengendali

Definisi TypeScript untuk berbagai metode callback telah dinormalisasi. Hal ini akan memberikan pengalaman yang lebih baik bagi developer yang menggunakan TypeScript dan menulis kode mereka sendiri untuk mengimplementasikan atau memanggil pengendali.

workbox-window

Metode messageSkipWaiting() baru

Metode baru, messageSkipWaiting(), telah ditambahkan ke modul workbox-window untuk menyederhanakan proses memberi tahu "waiting" service worker untuk diaktifkan. Hal ini menawarkan beberapa peningkatan:

  • Fungsi ini memanggil postMessage() dengan isi pesan standar de facto, {type: 'SKIP_WAITING'}, yang diperiksa oleh pekerja layanan yang dihasilkan oleh Workbox untuk memicu skipWaiting().
  • Library ini memilih pekerja layanan "menunggu" yang benar untuk memposting pesan ini, meskipun bukan pekerja layanan yang sama dengan yang didaftarkan workbox-window.

Penghapusan peristiwa "external" dan diganti dengan properti isExternal

Semua peristiwa "eksternal" di workbox-window telah dihapus dan diganti dengan peristiwa "normal" dengan properti isExternal yang ditetapkan ke true. Hal ini memungkinkan developer yang peduli dengan perbedaan tersebut untuk tetap mendeteksinya, dan developer yang tidak perlu tahu dapat mengabaikan properti tersebut.

Resep "Menawarkan pemuatan ulang halaman untuk pengguna" yang lebih rapi

Berkat kedua perubahan di atas, resep "Menawarkan pemuatan ulang halaman untuk pengguna" dapat disederhanakan:

// v6:
<script type="module">
  import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.0.0-alpha.1/workbox-window.prod.mjs';

  if ('serviceWorker' in navigator) {
    const wb = new Workbox('/sw.js');

    const showSkipWaitingPrompt = () => {
      // This assumes a hypothetical createUIPrompt() method with
      // onAccept and onReject callbacks:
      const prompt = createUIPrompt({
        onAccept: () => {
          wb.addEventListener('controlling', () => {
            window.location.reload();
          });

          // This will postMessage() to the waiting service worker.
          wb.messageSkipWaiting();
        },

        onReject: () => {
          prompt.dismiss();
        },
      });
    };

    // Listening for externalwaiting is no longer needed.
    wb.addEventListener('waiting', showSkipWaitingPrompt);
    wb.register();
  }
</script>

workbox-routing

Parameter boolean baru, sameOrigin, diteruskan ke fungsi matchCallback yang digunakan di workbox-routing. Nilainya ditetapkan ke true jika permintaan ditujukan untuk URL origin yang sama, dan false jika tidak.

Hal ini menyederhanakan beberapa boilerplate umum:

// In v5:
registerRoute(
  ({url}) =>
    url.origin === self.location.origin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

// In v6:
registerRoute(
  ({sameOrigin, url}) => sameOrigin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

matchOptions di workbox-expiration

Anda kini dapat menetapkan matchOptions di workbox-expiration, yang kemudian akan diteruskan sebagai CacheQueryOptions ke panggilan cache.delete() yang mendasarinya. (Sebagian besar developer tidak perlu melakukan ini.)

workbox-precaching

Menggunakan workbox-strategies

workbox-precaching telah ditulis ulang untuk menggunakan workbox-strategies sebagai dasar. Hal ini tidak akan menyebabkan perubahan yang dapat menyebabkan gangguan, dan akan menghasilkan konsistensi jangka panjang yang lebih baik dalam cara kedua modul mengakses jaringan dan cache.

Pra-cache kini memproses entri satu per satu, bukan secara massal

workbox-precaching telah diperbarui sehingga hanya satu entri dalam manifes precache yang diminta dan di-cache pada satu waktu, bukan mencoba meminta dan meng-cache semuanya sekaligus (menyerahkan kepada browser untuk mencari tahu cara membatasi).

Hal ini akan mengurangi kemungkinan error net::ERR_INSUFFICIENT_RESOURCES saat melakukan precaching, dan juga akan mengurangi pertentangan bandwidth antara precaching dan permintaan simultan yang dibuat oleh aplikasi web.

PrecacheFallbackPlugin memudahkan penggantian offline

workbox-precaching kini menyertakan PrecacheFallbackPlugin, yang mengimplementasikan metode siklus proses handlerDidError baru yang ditambahkan di v6.

Hal ini memudahkan penentuan URL yang di-precaching sebagai "penggantian" untuk strategi tertentu saat respons tidak tersedia. Plugin akan membuat kunci cache yang benar untuk URL yang di-precache, termasuk parameter revisi yang diperlukan.

Berikut adalah contoh penggunaannya untuk merespons dengan /offline.html yang di-cache sebelumnya saat strategi NetworkOnly tidak dapat menghasilkan respons untuk permintaan navigasi—dengan kata lain, menampilkan halaman HTML offline kustom:

import {PrecacheFallbackPlugin, precacheAndRoute} from 'workbox-precaching';
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

// Ensure that /offline.html is part of your precache manifest!
precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({request}) => request.mode === 'navigate',
  new NetworkOnly({
    plugins: [
      new PrecacheFallbackPlugin({
        fallbackURL: '/offline.html',
      }),
    ],
  })
);

precacheFallback dalam caching runtime

Jika Anda menggunakan generateSW untuk membuat pekerja layanan, bukan menulis pekerja layanan secara manual, Anda dapat menggunakan opsi konfigurasi precacheFallback baru di runtimeCaching untuk mencapai hal yang sama:

{
  // ... other generateSW config options...
  runtimeCaching: [{
    urlPattern: ({request}) => request.mode === 'navigate',
    handler: 'NetworkOnly',
    options: {
      precacheFallback: {
        // This URL needs to be included in your precache manifest.
        fallbackURL: '/offline.html',
      },
    },
  }],
}

Mendapatkan Bantuan

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