Bermigrasi dari Workbox v5 ke v6

Panduan ini berfokus pada perubahan yang menyebabkan error yang diperkenalkan di Workbox v6, dengan contoh perubahan yang perlu Anda buat 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 biasanya tidak umum.
  • Parameter kueri URL fbclid kini diabaikan oleh workbox-precaching saat mencari respons yang di-cache sebelumnya untuk permintaan tertentu.
  • Konstruktor PrecacheController kini menggunakan objek dengan properti tertentu sebagai parameternya, bukan string. Objek ini mendukung properti berikut: cacheName (berfungsi sama seperti string yang diteruskan ke konstruktor di v5), plugins (mengganti metode addPlugins() dari v5), dan fallbackToNetwork (mengganti 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.) Class ini 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. Sebagai gantinya, 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 "sebenarnya" yang menggunakan class Router workbox-routing di balik layar. Hal ini dapat menyebabkan urutan evaluasi rute yang berbeda jika Anda menyelang-seling panggilan ke registerRoute() dan precacheAndRoute().

perutean workbox

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

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

Build Configuration

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.

Alat Build 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 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 yang 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 yang ditangani strategi.

Class "handler" baru

Sebelumnya, kami memiliki modul internal yang memanggil 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 ditampilkan kepada developer.

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

Class ini juga akan 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 diteruskan objek state baru. Objek status ini akan unik untuk objek plugin tertentu dan pemanggilan strategi tertentu ini (yaitu panggilan ke handle()). Hal ini memungkinkan developer menulis plugin dengan satu callback yang dapat melakukan sesuatu secara kondisional 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 status siklus proses plugin sepenuhnya:

  • 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 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 yang dilakukan oleh plugin lain.
  • handlerDidComplete: dipanggil setelah semua extend lifetime promises yang ditambahkan ke peristiwa dari pemanggilan strategi ini telah diselesaikan. Callback ini dapat digunakan untuk melaporkan data apa pun yang perlu menunggu hingga pengendali selesai untuk dihitung (misalnya, status hit cache, 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 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 dinormalkan. Hal ini akan menghasilkan pengalaman yang lebih baik bagi developer yang menggunakan TypeScript dan menulis kode mereka sendiri untuk menerapkan atau memanggil pengendali.

workbox-window

Metode messageSkipWaiting() baru

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

Penghapusan peristiwa "eksternal" yang diganti dengan properti isExternal

Semua peristiwa "eksternal" 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 tersebut.

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

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

MULTI_LINE_CODE_PLACEHOLDER_0

workbox-routing

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

Hal ini menyederhanakan beberapa boilerplate umum:

MULTI_LINE_CODE_PLACEHOLDER_1

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 melakukannya.)

workbox-precaching

Menggunakan strategi workbox

workbox-precaching telah ditulis ulang untuk menggunakan workbox-strategies sebagai dasar. Hal ini seharusnya tidak menyebabkan perubahan yang dapat menyebabkan gangguan, dan akan menghasilkan konsistensi jangka panjang yang lebih baik dalam 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 pra-cache yang diminta dan di-cache pada satu waktu, bukan mencoba meminta dan meng-cache semuanya sekaligus (membiarkannya ke browser untuk mencari tahu cara men-throttle).

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

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

Hal ini memudahkan Anda menentukan URL yang di-cache sebelumnya sebagai "fallback" untuk strategi tertentu jika respons tidak tersedia. Plugin akan menangani pembuatan kunci cache yang benar untuk URL yang di-cache sebelumnya dengan benar, 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:

MULTI_LINE_CODE_PLACEHOLDER_2

precacheFallback dalam cache runtime

Jika Anda menggunakan generateSW untuk membuat pekerja layanan secara otomatis 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 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.