Workbox-webpack-plugin

Workbox ma dwie wtyczki webpack: jedna, która generuje dla Ciebie kompletny skrypt service worker, i druga, która generuje listę zasobów do wstępnego buforowania, które są wstrzykiwane w pliku skryptu service worker.

Wtyczki są wdrożone w module workbox-webpack-plugin jako 2 klasy o nazwach GenerateSW i InjectManifest. Odpowiedzi na poniższe pytania pomogą Ci wybrać odpowiednią wtyczkę i konfigurację.

Której wtyczki używać

GenerateSW

Wtyczka GenerateSW utworzy dla Ciebie plik skryptu service worker i doda go do potoku zasobów pakietu webpack.

Kiedy używać GenerateSW

  • Chcesz buforować pliki.
  • Nie ma potrzeby tworzenia pamięci podręcznej środowiska wykonawczego.

Kiedy NIE używać GenerateSW

  • Chcesz użyć innych funkcji skryptu Service Worker (np. Web Push).
  • Chcesz zaimportować dodatkowe skrypty lub dodać dodatkowe funkcje logiczne niestandardowych strategii buforowania.

InjectManifest

Wtyczka InjectManifest wygeneruje listę adresów URL do wstępnego buforowania i dodaje plik manifestu precache do istniejącego pliku skryptu service worker. W przeciwnym razie plik pozostanie bez zmian.

Kiedy używać InjectManifest

  • Chcesz mieć większą kontrolę nad skryptem service worker.
  • Chcesz buforować pliki.
  • Musisz dostosować trasy i strategie.
  • Chcesz używać skryptu service worker z innymi funkcjami platformy (np. Web Push).

Kiedy NIE używać InjectManifest

  • Chcesz dodać skrypt service worker do swojej witryny?

Wtyczka GenerateSW

Możesz dodać wtyczkę GenerateSW do konfiguracji pakietu internetowego w ten sposób:

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

Spowoduje to wygenerowanie skryptu service worker z wstępnym ustawieniem zapisywania w pamięci podręcznej dla wszystkich zasobów pakietu internetowego pobranych przez Twoją konfigurację oraz podanych reguł buforowania w czasie działania.

Pełny zestaw opcji konfiguracyjnych można znaleźć w dokumentacji referencyjnej.

Wtyczka InjectManifest

Możesz dodać wtyczkę InjectManifest do konfiguracji pakietu internetowego w ten sposób:

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

Spowoduje to utworzenie pliku manifestu precache na podstawie zasobów pakietu internetowego zebranych przez konfigurację i wstrzyknięcie go do pakietu i skompilowanego pliku skryptu service worker.

Pełny zestaw opcji konfiguracyjnych można znaleźć w dokumentacji referencyjnej.

Dodatkowe informacje

Wskazówki dotyczące używania wtyczek w kontekście większej kompilacji pakietu webowego znajdziesz w sekcji „Progressive Web Application” (Progresywna aplikacja internetowa) w dokumentacji tego pakietu.

Typy

GenerateSW

Ta klasa umożliwia tworzenie nowego, gotowego do użycia pliku skryptu service worker w ramach procesu kompilacji pakietu webpack.

Użyj instancji GenerateSW w tablicy plugins konfiguracji pakietu internetowego.

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

Właściwości

GenerateSWConfig

Właściwości

  • additionalManifestEntries

    (ciąg znaków | ManifestEntry)[] opcjonalnie

    Lista wpisów do wczytania w pamięci podręcznej, wraz z wpisami generowanymi w ramach konfiguracji kompilacji.

  • babelPresetEnvTargets

    string[] opcjonalny

    Wartość domyślna to: ["chrome >= 56"].

    Cele, które mają być przekazywane do babel-preset-env podczas transpilacji pakietu skryptu service worker.

  • cacheId

    ciąg znaków opcjonalny

    Opcjonalny identyfikator dołączany do nazw pamięci podręcznej. Jest to przydatne przede wszystkim w przypadku programowania lokalnego, w którym wiele witryn może być udostępnianych z tego samego źródła http://localhost:port.

  • fragmenty

    string[] opcjonalny

    Co najmniej jedna nazwa fragmentu, której odpowiednie pliki wyjściowe powinny być uwzględnione w pliku manifestu precache.

  • cleanupOutdatedCaches

    wartość logiczna opcjonalna

    Wartość domyślna to false (fałsz).

    Określa, czy Workbox ma próbować identyfikować i usuwać pamięć podręczną utworzone przez starsze, niezgodne wersje.

  • clientsClaim

    wartość logiczna opcjonalna

    Wartość domyślna to false (fałsz).

    Określa, czy skrypt service worker powinien rozpocząć kontrolowanie istniejących klientów zaraz po aktywacji.

  • directoryIndex

    ciąg znaków opcjonalny

    Jeśli żądanie nawigacji dla adresu URL z końcówką / nie pasuje do wstępnie zapisanego adresu URL, ta wartość zostaje dodana do adresu URL i sprawdzana pod kątem zgodności z pamięci podręcznej. W tym polu powinien być ustawiony adres używany przez serwer WWW na potrzeby indeksu katalogu.

  • disableDevLogs

    wartość logiczna opcjonalna

    Wartość domyślna to false (fałsz).

  • dontCacheBustURLsMatching

    Wyrażenie regularne opcjonalne

    Przyjmujemy, że zasoby pasujące do tych wartości mają unikalne wersje przypisane do ich adresu URL i są wykluczone z typowego pomijania pamięci podręcznej HTTP podczas wypełniania pamięci podręcznej. Chociaż nie jest to wymagane, zalecamy, aby jeśli obecny proces kompilacji już wstawiał wartość [hash] do każdej nazwy pliku, musisz podać wyrażenie regularne, które to wykryje, ponieważ zmniejszy to przepustowość wykorzystywaną podczas wstępnego buforowania.

  • wyklucz

    (ciąg znaków | Wyrażenie regularne | funkcja)[] opcjonalnie

    Co najmniej 1 specyfikator użyty do wykluczenia zasobów z pliku manifestu Precache. Jest to interpretowane zgodnie z tymi samymi regułami co standardowa opcja exclude parametru webpack. Jeśli nie podasz żadnej wartości, domyślną wartością będzie [/\.map$/, /^manifest.*\.js$].

  • excludeChunks

    string[] opcjonalny

    Co najmniej jedna nazwa fragmentu, której odpowiednie pliki wyjściowe powinny być wykluczone z pliku manifestu precache.

  • ignoreURLParametersMatching

    RegExp[] opcjonalny

    Wszystkie nazwy parametrów wyszukiwania, które pasują do jednego z wyrażeń regularnych w tej tablicy, zostaną usunięte przed wyszukaniem dopasowania w pamięci podręcznej. Jest to przydatne, gdy użytkownicy mogą prosić o adresy URL zawierające na przykład parametry adresu URL służące do śledzenia źródła ruchu. Jeśli nie podasz żadnej wartości, domyślną wartością będzie [/^utm_/, /^fbclid$/].

  • importScripts

    string[] opcjonalny

    Lista plików JavaScript, które należy przekazać do importScripts() w wygenerowanym pliku skryptu service worker. Jest to przydatne, gdy chcesz pozwolić Workbox na utworzenie pliku skryptu service worker najwyższego poziomu, ale chcesz dołączyć dodatkowy kod, na przykład detektor zdarzeń push.

  • importScriptsViaChunks

    string[] opcjonalny

    Co najmniej jedna nazwa fragmentu pakietu internetowego. Zawartość tych fragmentów zostanie włączona do wygenerowanego skryptu service worker przez wywołanie metody importScripts().

  • uwzględnij

    (ciąg znaków | Wyrażenie regularne | funkcja)[] opcjonalnie

    Co najmniej 1 specyfikator służący do dołączania zasobów do pliku manifestu precache. Jest to interpretowane zgodnie z tymi samymi regułami co standardowa opcja include parametru webpack.

  • inlineWorkboxRuntime

    wartość logiczna opcjonalna

    Wartość domyślna to false (fałsz).

    Określa, czy kod środowiska wykonawczego dla biblioteki Workbox ma być zawarty w skryptach service worker najwyższego poziomu czy podzielony na oddzielny plik, który trzeba wdrożyć razem z tym mechanizmem. Oddzielenie środowiska wykonawczego oznacza, że użytkownicy nie będą musieli ponownie pobierać kodu Workbox za każdym razem, gdy zmieni się skrypt service worker najwyższego poziomu.

  • manifestEntries

    ManifestEntry[] opcjonalnie

  • manifestTransforms

    ManifestTransform[] opcjonalny

    Co najmniej 1 funkcja, która zostanie zastosowana sekwencyjnie do wygenerowanego pliku manifestu. Jeśli podano też wartości modifyURLPrefix lub dontCacheBustURLsMatching, najpierw zostaną zastosowane odpowiadające im przekształcenia.

  • maximumFileSizeToCacheInBytes

    Liczba opcjonalnie

    Wartość domyślna to 2097152.

    Na podstawie tej wartości można określić maksymalny rozmiar plików, które będą wstępnie przechowywane w pamięci podręcznej. Zapobiega to przypadkowemu wyświetlaniu bardzo dużych plików, które mogłyby przypadkowo pasować do jednego z Twoich wzorców.

  • tryb

    ciąg znaków opcjonalny

    Jeśli ustawiona jest wartość „production”, zostanie utworzony zoptymalizowany pakiet skryptu service worker bez danych debugowania. Jeśli nie skonfigurujesz tutaj wyraźnie wartości mode, użyjemy wartości mode skonfigurowanej w bieżącej kompilacji webpack.

  • modifyURLPrefix

    obiekt opcjonalnie

    Ciąg mapowania obiektu poprzedza prefiksy zastępczego ciągu znaków. Można go użyć do np. usunięcia lub dodania prefiksu ścieżki z wpisu w pliku manifestu, jeśli Twoja konfiguracja hostingu WWW nie jest zgodna z konfiguracją lokalnego systemu plików. Jako alternatywę o większej elastyczności możesz użyć opcji manifestTransforms i udostępnić funkcję, która modyfikuje wpisy w pliku manifestu za pomocą dowolnej podanej logiki.

    Przykład użycia:

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

    ciąg znaków opcjonalny

    Wartość domyślna to null.

    Jeśli określisz to ustawienie, wszystkie żądania nawigacji dla adresów URL, które nie są wstępnie zapisane w pamięci podręcznej, będą realizowane za pomocą kodu HTML podanego pod podanym adresem URL. Musisz przekazać adres URL dokumentu HTML wymienionego w pliku manifestu precache. Ta wskazówka ma być używana w scenariuszu aplikacji jednostronicowej, w którym wszystkie elementy nawigacyjne mają używać standardowego kodu HTML App Shell.

  • navigateFallbackAllowlist

    RegExp[] opcjonalny

    Opcjonalna tablica wyrażeń regularnych ograniczająca adresy URL, do których ma zastosowanie skonfigurowane działanie navigateFallback. Jest to przydatne, gdy tylko część adresów URL witryny powinna być traktowana jak część aplikacji jednostronicowej. Jeśli skonfigurowano zarówno navigateFallbackDenylist, jak i navigateFallbackAllowlist, pierwszeństwo ma lista odrzuconych.

    Uwaga: te wyrażenia regularne mogą być oceniane w odniesieniu do każdego docelowego adresu URL podczas nawigacji. Unikaj złożonych wyrażeń regularnych, ponieważ w przeciwnym razie użytkownicy mogą zauważyć opóźnienia w poruszaniu się po witrynie.

  • navigateFallbackDenylist

    RegExp[] opcjonalny

    Opcjonalna tablica wyrażeń regularnych ograniczająca adresy URL, do których ma zastosowanie skonfigurowane działanie navigateFallback. Jest to przydatne, gdy tylko podzbiór adresów URL witryny powinien być traktowany jako część aplikacji jednostronicowej. Jeśli skonfigurowano zarówno navigateFallbackDenylist, jak i navigateFallbackAllowlist, ma pierwszeństwo przed listą odrzuconych.

    Uwaga: te wyrażenia regularne mogą być oceniane w odniesieniu do każdego docelowego adresu URL podczas nawigacji. Unikaj złożonych wyrażeń regularnych, ponieważ w przeciwnym razie użytkownicy mogą zauważyć opóźnienia w poruszaniu się po witrynie.

  • navigationPreload

    wartość logiczna opcjonalna

    Wartość domyślna to false (fałsz).

    Określa, czy włączyć wstępne wczytywanie nawigacji w wygenerowanym mechanizmie Service Worker. Jeśli zasada ma wartość Prawda, musisz też używać runtimeCaching, aby skonfigurować odpowiednią strategię reagowania, która będzie dopasowywana do żądań nawigacji, i wykorzystać wstępnie wczytywaną odpowiedź.

  • offlineGoogleAnalytics

    boolean | GoogleAnalyticsInitializeOptions opcjonalnie

    Wartość domyślna to false (fałsz).

    Określa, czy chcesz obsługiwać Google Analytics offline. Gdy true, wywołanie metody initialize() serwera workbox-google-analytics zostanie dodane do wygenerowanego skryptu service worker. Gdy ustawisz wartość Object, obiekt będzie przekazywany do wywołania initialize(), co umożliwi Ci dostosowanie działania.

  • runtimeCaching

    RuntimeCaching[] opcjonalny

    Gdy używasz narzędzi do kompilacji Workbox do generowania skryptu service worker, możesz określić co najmniej 1 konfigurację buforowania środowiska wykonawczego. Są one następnie przekształcane w wywołania workbox-routing.registerRoute za pomocą zdefiniowanej przez Ciebie konfiguracji dopasowania i obsługi.

    Wszystkie opcje znajdziesz w dokumentacji workbox-build.RuntimeCaching. Przykład poniżej przedstawia typową konfigurację ze zdefiniowanymi 2 trasami środowiska wykonawczego:

  • skipWaiting

    wartość logiczna opcjonalna

    Wartość domyślna to false (fałsz).

    Określa, czy dodać bezwarunkowe wywołanie do skipWaiting() do wygenerowanego skryptu service worker. Jeśli ustawiona jest wartość false, zamiast tego zostanie dodany detektor message, który umożliwi stronom klienta wywoływanie skipWaiting() przez wywołanie postMessage({type: 'SKIP_WAITING'}) w oczekującym module service worker.

  • mapa źródeł

    wartość logiczna opcjonalna

    Wartość domyślna to true.

    Określa, czy utworzyć mapę źródeł dla wygenerowanych plików skryptu service worker.

  • swDest

    ciąg znaków opcjonalny

    Wartość domyślna to "service-worker.js".

    Nazwa zasobu pliku skryptu service worker utworzonego przez tę wtyczkę.

InjectManifest

Ta klasa umożliwia kompilowanie pliku skryptu service worker udostępnionego przez swSrc oraz wstawianie do niego listy adresów URL i informacji o wersji na potrzeby wstępnego buforowania na podstawie potoku zasobów pakietu webpack.

Użyj instancji InjectManifest w tablicy plugins konfiguracji pakietu internetowego.

Oprócz wstrzyknięcia pliku manifestu ta wtyczka wykona kompilację pliku swSrc przy użyciu opcji z głównej konfiguracji pakietu webpack.

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

Właściwości

  • konstruktor

    void

    Tworzy instancję InjectManifest.

    Funkcja constructor wygląda tak:

    (config: WebpackInjectManifestOptions) => {...}

    • konfiguracja

      WebpackInjectManifestOptions

  • konfiguracja

    WebpackInjectManifestOptions

Właściwości

default

Typ

obiekt

Właściwości

  • GenerateSW

    zapytanie

  • InjectManifest

    zapytanie