workbox-webpack-plugin

Workbox menyediakan dua plugin webpack: satu plugin yang menghasilkan service worker lengkap untuk Anda dan satu plugin yang menghasilkan daftar aset untuk di-precache yang dimasukkan ke dalam file service worker.

Plugin diterapkan sebagai dua class dalam modul workbox-webpack-plugin, yang bernama GenerateSW dan InjectManifest. Jawaban atas pertanyaan berikut dapat membantu Anda memilih plugin dan konfigurasi yang tepat untuk digunakan.

Plugin yang Akan Digunakan

GenerateSW

Plugin GenerateSW akan membuat file pekerja layanan untuk Anda dan menambahkannya ke pipeline aset webpack.

Kapan menggunakan GenerateSW

  • Anda ingin melakukan pra-cache file.
  • Anda memiliki kebutuhan caching runtime sederhana.

Kapan TIDAK boleh menggunakan GenerateSW

  • Anda ingin menggunakan fitur Service Worker lainnya (yaitu Web Push).
  • Anda ingin mengimpor skrip tambahan, atau menambahkan logika tambahan untuk strategi penyimpanan dalam cache kustom.

InjectManifest

Plugin InjectManifest akan membuat daftar URL untuk di-precache dan menambahkan manifes precache tersebut ke file pekerja layanan yang ada. Jika tidak, file akan dibiarkan apa adanya.

Kapan menggunakan InjectManifest

  • Anda ingin memiliki lebih banyak kontrol atas pekerja layanan Anda.
  • Anda ingin melakukan pra-cache file.
  • Anda perlu menyesuaikan pemilihan rute dan strategi.
  • Anda ingin menggunakan pekerja layanan dengan fitur platform lainnya (misalnya, Web Push).

Kapan TIDAK boleh menggunakan InjectManifest

  • Anda menginginkan jalur termudah untuk menambahkan pekerja layanan ke situs Anda.

Plugin GenerateSW

Anda dapat menambahkan plugin GenerateSW ke konfigurasi webpack seperti berikut:

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      navigateFallback: '...',
      runtimeCaching: [{
        // Routing via a matchCallback function:
        urlPattern: ({request, url}) => ...,
        handler: '...',
        options: {
          cacheName: '...',
          expiration: {
            maxEntries: ...,
          },
        },
      }, {
        // Routing via a RegExp:
        urlPattern: new RegExp('...'),
        handler: '...',
        options: {
          cacheName: '...',
          plugins: [..., ...],
        },
      }],
      skipWaiting: ...,
    }),
  ],
};

Tindakan ini akan menghasilkan pekerja layanan dengan penyiapan precaching untuk semua aset webpack yang diambil oleh konfigurasi Anda, dan aturan caching runtime yang disediakan.

Kumpulan lengkap opsi konfigurasi dapat ditemukan di dokumentasi referensi.

Plugin InjectManifest

Anda dapat menambahkan plugin InjectManifest ke konfigurasi webpack seperti berikut:

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      swSrc: '...',
    }),
  ],
};

Cara ini akan membuat manifes precache berdasarkan aset webpack yang diambil oleh konfigurasi Anda dan memasukkannya ke dalam file pekerja layanan yang dipaketkan dan dikompilasi.

Kumpulan opsi konfigurasi lengkap dapat ditemukan dalam dokumentasi referensi.

Info Tambahan

Panduan tentang cara menggunakan plugin dalam konteks build webpack yang lebih besar dapat ditemukan di bagian "Progressive Web Application" dalam dokumentasi webpack.

Jenis

GenerateSW

Class ini mendukung pembuatan file pekerja layanan baru dan siap digunakan sebagai bagian dari proses kompilasi webpack.

Gunakan instance GenerateSW dalam array plugins dari konfigurasi webpack.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

Properti

GenerateSWConfig

Properti

  • additionalManifestEntries

    (string | ManifestEntry)[] opsional

    Daftar entri yang akan di-pra-cache, selain entri yang dihasilkan sebagai bagian dari konfigurasi build.

  • babelPresetEnvTargets

    string[] opsional

    Nilai defaultnya adalah: ["chrome >= 56"]

    target yang akan diteruskan ke babel-preset-env saat melakukan transpilasi paket pekerja layanan.

  • cacheId

    string opsional

    ID opsional yang akan ditambahkan ke nama cache. Hal ini terutama berguna untuk pengembangan lokal saat beberapa situs mungkin ditayangkan dari asal http://localhost:port yang sama.

  • potongan

    string[] opsional

    Satu atau beberapa nama potongan yang file outputnya terkait harus disertakan dalam manifes precache.

  • cleanupOutdatedCaches

    boolean opsional

    Nilai defaultnya adalah: false

    Apakah Workbox harus mencoba mengidentifikasi dan menghapus precache apa pun yang dibuat oleh versi lama yang tidak kompatibel.

  • clientsClaim

    boolean opsional

    Nilai defaultnya adalah: false

    Apakah pekerja layanan harus mulai mengontrol klien yang ada segera setelah diaktifkan.

  • directoryIndex

    string opsional

    Jika permintaan navigasi untuk URL yang diakhiri dengan / gagal cocok dengan URL yang di-cache sebelumnya, nilai ini akan ditambahkan ke URL dan akan diperiksa untuk menemukan kecocokan cache sebelumnya. Ini harus ditetapkan ke server web yang Anda gunakan untuk indeks direktorinya.

  • disableDevLogs

    boolean opsional

    Nilai defaultnya adalah: false

  • dontCacheBustURLsMatching

    Regexp opsional

    Aset yang cocok dengan ini akan diasumsikan memiliki versi unik melalui URL-nya, dan dikecualikan dari penghapusan cache HTTP normal yang dilakukan saat mengisi pra-cache. Meskipun tidak diperlukan, sebaiknya jika proses build yang ada sudah menyisipkan nilai [hash] ke dalam setiap nama file, Anda memberikan RegExp yang akan mendeteksinya, karena akan mengurangi bandwidth yang digunakan saat melakukan pra-cache.

  • kecualikan

    (string | RegExp | function)[] opsional

    Satu atau beberapa penentu yang digunakan untuk mengecualikan aset dari manifes pra-cache. Ini ditafsirkan dengan mengikuti aturan yang sama seperti opsi exclude standar webpack. Jika tidak diberikan, nilai defaultnya adalah [/\.map$/, /^manifest.*\.js$].

  • excludeChunks

    string[] opsional

    Satu atau beberapa nama bagian yang file output-nya harus dikecualikan dari manifes pra-cache.

  • ignoreURLParametersMatching

    RegExp[] opsional

    Setiap nama parameter penelusuran yang cocok dengan salah satu RegExp dalam array ini akan dihapus sebelum mencari kecocokan pra-cache. Hal ini berguna jika pengguna Anda mungkin meminta URL yang berisi, misalnya, parameter URL yang digunakan untuk melacak sumber traffic. Jika tidak diberikan, nilai defaultnya adalah [/^utm_/, /^fbclid$/].

  • importScripts

    string[] opsional

    Daftar file JavaScript yang harus diteruskan ke importScripts() di dalam file service worker yang dihasilkan. Hal ini berguna saat Anda ingin mengizinkan Workbox membuat file pekerja layanan tingkat atas, tetapi ingin menyertakan beberapa kode tambahan, seperti pemroses peristiwa push.

  • importScriptsViaChunks

    string[] opsional

    Satu atau beberapa nama bagian webpack. Konten potongan tersebut akan disertakan dalam pekerja layanan yang dihasilkan, melalui panggilan ke importScripts().

  • sertakan

    (string | Ekspresi reguler | fungsi)[] opsional

    Satu atau beberapa penentu yang digunakan untuk menyertakan aset dalam manifes pra-cache. Ini ditafsirkan dengan mengikuti aturan yang sama seperti opsi include standar webpack.

  • inlineWorkboxRuntime

    boolean opsional

    Nilai defaultnya adalah: false

    Apakah kode runtime untuk library Workbox harus disertakan dalam pekerja layanan tingkat teratas, atau dibagi menjadi file terpisah yang perlu di-deploy bersama pekerja layanan. Memisahkan runtime berarti pengguna tidak perlu mendownload ulang kode Workbox setiap kali pekerja layanan tingkat atas Anda berubah.

  • manifestEntries

    ManifestEntry[] opsional

  • manifestTransforms

    ManifestTransform[] opsional

    Satu atau beberapa fungsi yang akan diterapkan secara berurutan terhadap manifes yang dihasilkan. Jika modifyURLPrefix atau dontCacheBustURLsMatching juga ditentukan, transformasi yang sesuai akan diterapkan terlebih dahulu.

  • maximumFileSizeToCacheInBytes

    number opsional

    Nilai defaultnya adalah: 2097152

    Nilai ini dapat digunakan untuk menentukan ukuran maksimum file yang akan di-pra-cache. Hal ini mencegah Anda melakukan pra-cache file yang sangat besar secara tidak sengaja yang mungkin tidak sengaja cocok dengan salah satu pola Anda.

  • mode

    string opsional

    Jika ditetapkan ke 'production', paket pekerja layanan yang dioptimalkan yang mengecualikan info proses debug akan dihasilkan. Jika tidak dikonfigurasi secara eksplisit di sini, nilai mode yang dikonfigurasi dalam kompilasi webpack saat ini akan digunakan.

  • modifyURLPrefix

    objek opsional

    Objek yang memetakan awalan string ke nilai string pengganti. Ini dapat digunakan untuk, misalnya, menghapus atau menambahkan awalan jalur dari entri manifes jika penyiapan hosting web Anda tidak cocok dengan penyiapan sistem file lokal Anda. Sebagai alternatif dengan fleksibilitas yang lebih besar, Anda dapat menggunakan opsi manifestTransforms dan menyediakan fungsi yang mengubah entri dalam manifes menggunakan logika apa pun yang Anda berikan.

    Contoh penggunaan:

    // Replace a '/dist/' prefix with '/', and also prepend
// '/static' to every URL.
modifyURLPrefix: {
  '/dist/': '/',
  '': '/static',
}
  • navigateFallback

    string opsional

    Nilai defaultnya adalah: null

    Jika ditentukan, semua permintaan navigasi untuk URL yang tidak dipra-cache akan dipenuhi dengan HTML di URL yang diberikan. Anda harus meneruskan URL dokumen HTML yang tercantum dalam manifes precache. Ini dimaksudkan untuk digunakan dalam skenario Aplikasi Satu Halaman, tempat Anda ingin semua navigasi menggunakan HTML Shell Aplikasi umum.

  • navigateFallbackAllowlist

    RegExp[] opsional

    Array ekspresi reguler opsional yang membatasi URL mana yang akan diterapkan oleh perilaku navigateFallback yang dikonfigurasi. Hal ini berguna jika hanya sebagian URL situs Anda yang harus diperlakukan sebagai bagian dari Aplikasi Web Satu Halaman. Jika navigateFallbackDenylist dan navigateFallbackAllowlist dikonfigurasi, daftar tolak akan diutamakan.

    Catatan: RegExp ini dapat dievaluasi terhadap setiap URL tujuan selama navigasi. Hindari penggunaan RegExp yang kompleks, atau pengguna mungkin akan melihat penundaan saat menjelajahi situs Anda.

  • navigateFallbackDenylist

    RegExp[] opsional

    Array ekspresi reguler opsional yang membatasi URL mana yang akan diterapkan oleh perilaku navigateFallback yang dikonfigurasi. Hal ini berguna jika hanya sebagian URL situs Anda yang harus diperlakukan sebagai bagian dari Aplikasi Web Satu Halaman. Jika navigateFallbackDenylist dan navigateFallbackAllowlist dikonfigurasi, daftar tolak akan diprioritaskan.

    Catatan: RegExp ini dapat dievaluasi terhadap setiap URL tujuan selama navigasi. Hindari penggunaan RegExp yang kompleks, atau pengguna mungkin akan melihat penundaan saat menjelajahi situs Anda.

  • navigationPreload

    boolean opsional

    Nilai defaultnya adalah: false

    Apakah akan mengaktifkan pramuat navigasi di pekerja layanan yang dihasilkan atau tidak. Jika disetel ke benar (true), Anda juga harus menggunakan runtimeCaching untuk menyiapkan strategi respons yang sesuai yang akan cocok dengan permintaan navigasi, dan menggunakan respons yang dimuat sebelumnya.

  • offlineGoogleAnalytics

    boolean | GoogleAnalyticsInitializeOptions opsional

    Nilai defaultnya adalah: false

    Mengontrol apakah akan menyertakan dukungan untuk Google Analytics offline atau tidak. Jika true, panggilan ke initialize() workbox-google-analytics akan ditambahkan ke pekerja layanan yang dihasilkan. Jika ditetapkan ke Object, objek tersebut akan diteruskan ke panggilan initialize(), sehingga Anda dapat menyesuaikan perilaku.

  • runtimeCaching

    RuntimeCaching[] opsional

    Saat menggunakan alat build Workbox untuk membuat pekerja layanan, Anda dapat menentukan satu atau beberapa konfigurasi penyimpanan dalam cache runtime. Hal ini kemudian diterjemahkan ke panggilan workbox-routing.registerRoute menggunakan konfigurasi pencocokan dan pengendali yang Anda tentukan.

    Untuk semua opsi, lihat dokumentasi workbox-build.RuntimeCaching. Contoh di bawah menunjukkan konfigurasi standar, dengan dua rute runtime yang ditentukan:

  • skipWaiting

    boolean opsional

    Nilai defaultnya adalah: false

    Apakah akan menambahkan panggilan tanpa syarat ke skipWaiting() ke service worker yang dihasilkan. Jika false, pemroses message akan ditambahkan, sehingga halaman klien dapat memicu skipWaiting() dengan memanggil postMessage({type: 'SKIP_WAITING'}) pada pekerja layanan yang menunggu.

  • sourcemap

    boolean opsional

    Nilai defaultnya adalah: true

    Apakah akan membuat sourcemap untuk file pekerja layanan yang dihasilkan.

  • swDest

    string opsional

    Nilai defaultnya adalah: "service-worker.js"

    Nama aset file pekerja layanan yang dibuat oleh plugin ini.

InjectManifest

Class ini mendukung kompilasi file pekerja layanan yang disediakan melalui swSrc, dan memasukkan daftar URL dan informasi revisi ke dalam pekerja layanan tersebut untuk pra-cache berdasarkan pipeline aset webpack.

Gunakan instance InjectManifest dalam array plugins dari konfigurasi webpack.

Selain menginjeksikan manifes, plugin ini akan melakukan kompilasi file swSrc, menggunakan opsi dari konfigurasi webpack utama.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new InjectManifest({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  swSrc: '...',
});

Properti

Properti

default

Jenis

objek

Properti

  • GenerateSW

    kueri

  • InjectManifest

    kueri