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.

{i>workbox-precaching<i}

  • Dokumen HTML lintas origin untuk URL yang terkait dengan pengalihan HTTP tidak dapat lagi digunakan untuk memenuhi permintaan navigasi dengan workbox-precaching. Skenario ini jarang terjadi.
  • Parameter kueri URL fbclid kini diabaikan oleh workbox-precaching saat mencari respons yang telah di-cache 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 sekarang mengambil tepat satu parameter, yang masing-masing 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. (Kode ini masih ada sebagai metode bantuan statis yang diekspor oleh modul workbox-precaching.) Atribut dihapus karena PrecacheRoute dapat digunakan sebagai gantinya.
  • Metode createMatchCalback() telah dihapus dari PrecacheController. Sebagai gantinya, PrecacheRoute baru dapat digunakan.
  • 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.
  • Rute yang didaftarkan dengan precacheAndRoute() sekarang merupakan rute "nyata" yang menggunakan class Router workbox-routing di balik layar. Hal ini dapat menyebabkan urutan evaluasi yang berbeda pada rute jika Anda menyisipkan panggilan ke registerRoute() dan precacheAndRoute().

perutean kotak kerja

Metode setDefaultHandler() kini mengambil parameter kedua opsional yang sesuai dengan metode HTTP yang diterapkan, yang ditetapkan secara default ke 'GET'.

  • Jika 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 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 dalam plugin InjectManifest-nya.

Build Tools Memerlukan Node.js v10 atau yang Lebih Tinggi

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

Peningkatan Baru

strategi-workbox

Workbox v6 memperkenalkan cara baru bagi developer pihak ketiga untuk menentukan strategi Workbox mereka sendiri. Hal ini memastikan bahwa 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 mereka memulai, merespons, dan mengakhiri).
  • Membuat instance "pengendali", yang dapat mengelola status untuk setiap permintaan yang ditangani strategi.

Class "handler" baru

Kami sebelumnya memiliki modul internal yang memanggil fetchWrapper dan cacheWrapper, yang (sesuai dengan 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 "pengendali" yang baru, StrategyHandler, akan menampilkan 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 akan memungkinkan developer menambahkan callback siklus proses kustom mereka sendiri yang mungkin spesifik untuk strategi mereka, dan mereka akan "bisa 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 menerima objek state baru. Objek status ini akan bersifat unik untuk objek plugin khusus ini dan pemanggilan strategi khusus ini (yaitu panggilan ke handle()). Hal ini memungkinkan developer untuk menulis plugin dengan satu callback dapat secara kondisional melakukan sesuatu berdasarkan apa yang dilakukan 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 status siklus proses plugin sepenuhnya:

  • handlerWillStart: dipanggil sebelum logika pengendali mulai berjalan. Callback ini dapat digunakan untuk menetapkan status pengendali awal (mis., merekam waktu mulai).
  • handlerWillRespond: dipanggil sebelum strategi metode handle() menampilkan respons. Callback ini dapat digunakan untuk mengubah respons tersebut sebelum mengembalikannya 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 dilakukan oleh plugin lain.
  • handlerDidComplete: dipanggil setelah semua perpanjang promise sepanjang waktu yang ditambahkan ke peristiwa dari pemanggilan strategi ini telah ditetapkan. 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 apa pun. Callback ini dapat digunakan untuk menyediakan konten "penggantian" sebagai alternatif error jaringan.

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

Jenis TypeScript yang lebih akurat untuk pengendali

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

jendela-kerja

Metode messageSkipMenunggu() baru

Metode baru, messageSkipWaiting(), telah ditambahkan ke modul workbox-window untuk menyederhanakan proses memberi tahu pekerja layanan"menunggu" agar aktif. Versi 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().
  • Fungsi ini memilih pekerja layanan "menunggu" yang benar untuk memposting pesan ini, meskipun itu bukan pekerja layanan yang sama dengan yang didaftarkan workbox-window.

Penghapusan peristiwa "eksternal" yang mendukung properti isExternal

Semua peristiwa "external" di workbox-window telah dihapus sebagai pengganti 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 mengetahuinya dapat mengabaikan properti ini.

Resep "Tawarkan pemuatan ulang halaman untuk pengguna" pada pembersih

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

MULTI_LINE_CODE_PLACEHOLDER_0

perutean kotak kerja

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

Cara ini menyederhanakan beberapa boilerplate umum:

MULTI_LINE_CODE_PLACEHOLDER_1

matchOptions di workbox-expiration

Anda sekarang 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.)

{i>workbox-precaching<i}

Menggunakan strategi kotak kerja

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

Precaching kini memproses entri satu per satu, bukan secara massal

workbox-precaching telah diupdate sehingga hanya satu entri dalam manifes precache yang diminta dan di-cache dalam satu waktu, bukan mencoba meminta dan meng-cache semuanya sekaligus (membiarkannya ke browser untuk mengetahui cara melakukan throttle).

Tindakan 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 memungkinkan penggantian offline yang lebih mudah

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

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

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

MULTI_LINE_CODE_PLACEHOLDER_2

precacheFallback dalam cache runtime

Jika Anda menggunakan generateSW guna membuat pekerja layanan untuk Anda, alih-alih menulis pekerja layanan secara manual, Anda dapat menggunakan opsi konfigurasi precacheFallback yang baru di runtimeCaching untuk melakukan 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 berharap sebagian besar migrasi mudah dilakukan. Jika Anda mengalami masalah yang tidak tercakup dalam panduan ini, beri tahu kami dengan membuka masalah di GitHub.