workbox-webpack-plugin

Workbox menyediakan dua plugin webpack: satu yang menghasilkan pekerja layanan lengkap untuk Anda, dan satu lagi yang menghasilkan daftar aset untuk melakukan precache yang dimasukkan ke file pekerja layanan.

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

{i>Plugin<i} 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 {i>precache<i} file.
  • Anda memiliki kebutuhan penyimpanan cache runtime yang sederhana.

Kapan GenerateSW TIDAK harus digunakan

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

InjectManifest

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

Kapan menggunakan InjectManifest

  • Anda menginginkan kontrol lebih besar atas pekerja layanan.
  • Anda ingin melakukan {i>precache<i} file.
  • Anda perlu menyesuaikan pemilihan rute dan strategi.
  • Anda ingin menggunakan pekerja layanan dengan fitur platform lainnya (mis. Web Push).

Kapan InjectManifest TIDAK harus digunakan

  • 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: ...,
    }),
  ],
};

Ini akan menghasilkan pekerja layanan dengan penyiapan pra-caching untuk semua aset webpack yang diambil oleh konfigurasi Anda, dan aturan caching runtime yang disediakan.

Set 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: '...',
    }),
  ],
};

Ini akan membuat manifes precache berdasarkan aset webpack yang diambil oleh konfigurasi Anda dan memasukkannya ke dalam file service worker yang dipaketkan dan dikompilasi.

Set lengkap opsi konfigurasi dapat ditemukan di dokumentasi referensi.

Info Tambahan

Panduan penggunaan 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 yang siap digunakan sebagai bagian dari proses kompilasi webpack.

Gunakan instance GenerateSW dalam array plugins pada 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-precache, selain setiap entri yang dibuat sebagai bagian dari konfigurasi build.

  • babelPresetEnvTargets

    string[] opsional

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

    Target yang akan diteruskan ke babel-preset-env saat mentranspilasi paket pekerja layanan.

  • cacheId

    string opsional

    ID opsional yang akan ditambahkan ke nama cache. Hal ini terutama berguna untuk pengembangan lokal, tempat beberapa situs dapat disalurkan 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 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 telah di-cache, nilai ini akan ditambahkan ke URL dan akan diperiksa untuk menemukan kecocokan precache. Atribut ini harus ditetapkan ke alamat yang digunakan server web Anda untuk indeks direktorinya.

  • disableDevLogs

    boolean opsional

    Nilai defaultnya adalah: false

  • dontCacheBustURLsMatching

    Ekspresi reguler opsional

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

  • kecualikan

    (string|RegExp|function)[] optional

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

  • excludeChunks

    string[] opsional

    Satu atau beberapa nama potongan yang file outputnya terkait harus dikecualikan dari manifes precache.

  • ignoreURLParametersMatching

    RegExp[] opsional

    Semua nama parameter penelusuran yang cocok dengan salah satu RegExp dalam array ini akan dihapus sebelum mencari pencocokan pra-cache. Hal ini berguna jika pengguna 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 pekerja layanan yang dihasilkan. Ini berguna jika Anda ingin mengizinkan Workbox membuat file pekerja layanan level teratas, tetapi ingin menyertakan beberapa kode tambahan, seperti pemroses peristiwa push.

  • importScriptsViaChunks

    string[] opsional

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

  • sertakan

    (string|RegExp|function)[] optional

    Satu atau beberapa penentu digunakan untuk menyertakan aset dalam manifes precache. Hal ini ditafsirkan dengan mengikuti aturan yang sama dengan opsi include standar webpack.

  • inlineWorkboxRuntime

    boolean opsional

    Nilai defaultnya adalah: false

    Apakah kode runtime untuk library Workbox harus disertakan dalam pekerja layanan tingkat atas, atau dibagi menjadi file terpisah yang perlu di-deploy bersama pekerja layanan. Dengan memisahkan runtime, pengguna tidak perlu mendownload ulang kode Workbox setiap kali pekerja layanan tingkat atas 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

    nomor opsional

    Nilai defaultnya adalah: 2097152

    Nilai ini dapat digunakan untuk menentukan ukuran maksimum file yang akan di-precache. Ini mencegah Anda secara tidak sengaja menyimpan file berukuran sangat besar yang mungkin tidak sengaja cocok dengan salah satu pola.

  • mode

    string opsional

    Jika ditetapkan ke 'production', paket pekerja layanan yang dioptimalkan dan tidak menyertakan info proses debug akan ditampilkan. 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. Sebagai alternatif dengan lebih fleksibel, 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 di-cache akan dipenuhi dengan HTML di URL yang diberikan. Anda harus meneruskan URL dokumen HTML yang tercantum dalam manifes precache Anda. Hal ini dimaksudkan untuk digunakan dalam skenario Aplikasi Satu Halaman, tempat Anda ingin semua navigasi menggunakan HTML Shell Aplikasi yang umum.

  • navigateFallbackAllowlist

    RegExp[] opsional

    Array opsional dari ekspresi reguler yang membatasi URL tempat perilaku navigateFallback yang dikonfigurasi diterapkan. 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 menjadi lebih diutamakan.

    Catatan: RegExp ini dapat dievaluasi terhadap setiap URL tujuan selama navigasi. Hindari penggunaan Ekspresi Reguler yang kompleks, atau pengguna mungkin akan mengalami keterlambatan saat membuka situs Anda.

  • navigateFallbackDenylist

    RegExp[] opsional

    Array opsional dari ekspresi reguler yang membatasi URL tempat perilaku navigateFallback yang dikonfigurasi diterapkan. 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 lebih diutamakan.

    Catatan: RegExp ini dapat dievaluasi terhadap setiap URL tujuan selama navigasi. Hindari penggunaan Ekspresi Reguler yang kompleks, atau pengguna mungkin akan mengalami keterlambatan saat membuka 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 dan akan cocok dengan permintaan navigasi, serta memanfaatkan respons pramuat.

  • offlineGoogleAnalytics

    boolean|GoogleAnalyticsInitializeOptions optional

    Nilai defaultnya adalah: false

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

  • runtimeCaching

    RuntimeCaching[] opsional

    Saat menggunakan alat build Workbox untuk menghasilkan pekerja layanan, Anda dapat menentukan satu atau beberapa konfigurasi penyimpanan cache runtime. 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 ini menunjukkan konfigurasi umum, dengan dua rute runtime yang ditentukan:

  • skipWaiting

    boolean opsional

    Nilai defaultnya adalah: false

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

  • peta sumber

    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 service worker 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 pekerja layanan tersebut untuk precache berdasarkan pipeline aset webpack.

Gunakan instance InjectManifest dalam array plugins pada konfigurasi webpack.

Selain memasukkan manifes, plugin ini akan menjalankan 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