Workbox-webpack-plugin

Workbox udostępnia 2 wtyczki webpack: jeden generuje dla Ciebie kompletny skrypt service worker, a drugi generuje listę zasobów do wstępnego buforowania, która jest wstrzykiwana do pliku service worker.

Wtyczki są zaimplementowane w module workbox-webpack-plugin w postaci 2 klas o nazwach GenerateSW i InjectManifest. Odpowiedzi na te pytania pomogą Ci wybrać odpowiedni wtyczkę i konfigurację.

Którego wtyczka używać

GenerateSW

Wtyczka GenerateSW utworzy dla Ciebie plik usługi dla usług i doda go do potoku komponentów webpacka.

Kiedy używać funkcji GenerateSW

  • Chcesz umieścić pliki w pamięci podręcznej.
  • Masz proste potrzeby buforowania środowiska wykonawczego.

Kiedy nie używać GenerateSW

  • Chcesz korzystać z innych funkcji Service Worker (np. Web Push).
  • Chcesz zaimportować dodatkowe skrypty lub zastosować dodatkowe funkcje logiczne dla niestandardowych strategii buforowania.

InjectManifest

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

Kiedy używać InjectManifest

  • Chcesz mieć większą kontrolę nad usługą.
  • chcesz wstępnie zapisać pliki.
  • Musisz dostosować kierowanie i strategie.
  • Chcesz używać swojego serwisu workera z innymi funkcjami platformy (np. Web Push).

Kiedy nie używać InjectManifest

  • Chcesz dowiedzieć się, jak najłatwiej dodać do witryny plik service worker.

Wtyczka GenerateSW

Wtyczkę GenerateSW możesz dodać do konfiguracji webpacka 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 usługi dla pracowników z wstępnym buforowaniem wszystkich zasobów webpacka wybranych przez konfigurację oraz podanych reguł buforowania w czasie wykonywania.

Pełny zestaw opcji konfiguracji znajdziesz w dokumentacji referencyjnej.

InjectManifest Wtyczka

Wtyczkę InjectManifest możesz dodać do konfiguracji webpacka 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 do wcześniejszego buforowania na podstawie zasobów webpacka wybranych przez konfigurację i wstrzyknięcie go do skompilowanego pliku usługi instancji roboczej.

Pełny zestaw opcji konfiguracji znajdziesz w dokumentacji referencyjnej.

Dodatkowe informacje

Wskazówki dotyczące używania wtyczek w kontekście większej kompilacji pakietu internetowego można znaleźć w sekcji „Progresywna aplikacja internetowa” w dokumentacji pakietu internetowego.

Typy

GenerateSW

Ta klasa obsługuje tworzenie nowego, gotowego do użycia pliku usługi w ramach procesu kompilacji webpack.

Użyj instancji GenerateSW w tablicy plugins w konfiguracji webpacka.

// 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

    (string | ManifestEntry)[] opcjonalnie

    Lista wpisów do wstępnego buforowania, a także wszystkich wpisów generowanych w ramach konfiguracji kompilacji.

  • babelPresetEnvTargets

    string[] opcjonalnie

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

    Cel, który ma być przekazany do babel-preset-env podczas transpilacji pakietu usługi.

  • cacheId

    ciąg znaków opcjonalny

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

  • fragmenty

    string[] opcjonalnie

    Nazwy co najmniej 1 elementu, którego odpowiadające pliki wyjściowe powinny zostać uwzględnione w pliku manifestu do wstępnego buforowania.

  • cleanupOutdatedCaches

    Wartość logiczna opcjonalna

    Wartość domyślna: false

    Określa, czy Workbox ma próbować zidentyfikować i usunąć wszystkie pamięci podręczne utworzone przez starsze, niezgodne wersje.

  • clientsClaim

    logiczna opcjonalna

    Wartość domyślna to false.

    Określ, czy usługa powinna zacząć kontrolować wszystkich dotychczasowych klientów od razu po aktywacji.

  • directoryIndex

    ciąg znaków opcjonalny

    Jeśli żądanie nawigacji dotyczące adresu URL kończącego się na / nie pasuje do wstępnie zapisanego adresu URL, ta wartość zostanie dodana do adresu URL i będzie sprawdzana pod kątem zgodności z pamięci podręcznej. Ta wartość powinna być taka sama jak ta, której używa serwer WWW do indeksu katalogu.

  • disableDevLogs

    logiczna opcjonalna

    Wartość domyślna to false.

  • dontCacheBustURLsMatching

    RegExp opcjonalny

    Zakłada się, że zasoby, które pasują do tego wzorca, mają unikalną wersję określoną za pomocą ich adresu URL i są wykluczone z normalnego burzenia pamięci podręcznej HTTP, które jest wykonywane podczas wypełniania pamięci podręcznej wstępnej. Chociaż nie jest to wymagane, jeśli istniejący proces kompilacji już wstawia wartość [hash] do nazwy każdego pliku, zalecamy podanie wyrażenia regularnego, które to wykryje, ponieważ pozwoli to zmniejszyć zużycie przepustowości podczas wstępnego buforowania.

  • wyklucz

    (ciąg | Wyrażenie regularne | funkcja)[] optional

    Co najmniej jeden specyfikator służący do wykluczania zasobów z pliku manifestu wstępnego pamięci podręcznej. Jest on interpretowany zgodnie z tymi samymi zasadami co standardowa opcja exclude w webpack. Jeśli nie podasz żadnej opcji, domyślna wartość to [/\.map$/, /^manifest.*\.js$].

  • excludeChunks

    string[] opcjonalnie

    Nazwy co najmniej 1 elementu, którego odpowiadające mu pliki wyjściowe powinny zostać wykluczone z manifesztu wstępnego.

  • ignoreURLParametersMatching

    RegExp[] opcjonalny

    Przed rozpoczęciem wyszukiwania dopasowania w pamięci podręcznej zostaną usunięte wszystkie nazwy parametrów wyszukiwania, które pasują do jednego z wyrażeń regularnych w tym tablicy. Jest to przydatne, jeśli użytkownicy mogą wysyłać żądania adresów URL zawierających np. parametry adresu URL używane do śledzenia źródła wizyt. Jeśli nie podasz żadnej opcji, domyślną wartością będzie [/^utm_/, /^fbclid$/].

  • importScripts

    string[] opcjonalnie

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

  • importScriptsViaChunks

    string[] opcjonalnie

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

  • uwzględnij

    (string | RegExp | function)[] opcjonalnie

    Jeden lub więcej wskaźników używanych do uwzględniania zasobów w pliku manifestu wstępnego buforowania. Jest on interpretowany zgodnie z tymi samymi zasadami co standardowa opcja include w webpack.

  • inlineWorkboxRuntime

    logiczna opcjonalna

    Wartość domyślna: false

    Określa, czy kod środowiska wykonawczego biblioteki Workbox powinien być uwzględniony w skrypcie service worker najwyższego poziomu czy w oddzielnym pliku, który trzeba wdrożyć razem z skrypcją service worker. Dzięki temu 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[] opcjonalnie

    Co najmniej 1 funkcja, która zostanie zastosowana sekwencyjnie do wygenerowanego pliku manifestu. Jeśli określono też modifyURLPrefix lub dontCacheBustURLsMatching, najpierw zostaną zastosowane odpowiednie przekształcenia.

  • maximumFileSizeToCacheInBytes

    number opcjonalny

    Wartość domyślna: 2097152

    Ta wartość może służyć do określania maksymalnego rozmiaru plików, które będą wstępnie wczytywane w pamięci podręcznej. Zapobiega to przypadkowemu wstępnemu buforowaniu bardzo dużych plików, które mogłyby przypadkowo pasować do jednego z Twoich wzorów.

  • tryb

    ciąg znaków opcjonalny

    Jeśli jest ustawiona na „production”, zostanie utworzony zoptymalizowany pakiet instancji roboczych bez danych debugowania. Jeśli nie zostanie skonfigurowana tutaj, zostanie użyta wartość mode skonfigurowana w bieżącej kompilacji webpack.

  • modifyURLPrefix

    obiekt opcjonalny

    Obiekt mapujący ciągi znaków prefiksów na wartości ciągu znaków zastępczych. Możesz go użyć np. do usunięcia lub dodania prefiksu ścieżki z elementu manifestu, jeśli konfiguracja hostingu internetowego nie pasuje do konfiguracji lokalnego systemu plików. Jako alternatywę możesz użyć opcji manifestTransforms i podać funkcję, która modyfikuje wpisy w pliku manifestu za pomocą dowolnej podanej przez Ciebie 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 to pole jest zaznaczone, wszystkie żądania nawigacji dotyczące adresów URL, które nie są wcześniej przechowywane w pamięci podręcznej, będą realizowane za pomocą kodu HTML z podawanego adresu URL. Musisz podać adres URL dokumentu HTML, który znajduje się w pliku manifestu domyślnego buforowania. Jest on przeznaczony do używania w sytuacji aplikacji jednostronicowej, w której chcesz, aby wszystkie elementy nawigacji używały wspólnego HTML w opakowaniu aplikacji.

  • navigateFallbackAllowlist

    Wyrażenie regularne[] opcjonalnie

    Opcjonalny tablica wyrażeń regularnych, która ogranicza zakres adresów URL, do których ma zastosowanie skonfigurowane zachowanie navigateFallback. Jest to przydatne, jeśli tylko podzbiór adresów URL w witrynie ma być traktowany jako część aplikacji jednostronicowej. Jeśli skonfigurujesz zarówno navigateFallbackDenylist, jak i navigateFallbackAllowlist, lista zaprzeczeń ma pierwszeństwo.

    Uwaga: podczas nawigacji te wyrażenia regularne mogą być oceniane na podstawie każdego adresu URL docelowego. Unikaj korzystania z złożonego wyrażenia regularnego, ponieważ może to spowodować opóźnienia w nawigacji po witrynie.

  • navigateFallbackDenylist

    Wyrażenie regularne[] opcjonalnie

    Opcjonalna tablica wyrażeń regularnych określająca adresy URL, do których ma zastosowanie skonfigurowane działanie navigateFallback. Jest to przydatne, jeśli tylko podzbiór adresów URL witryny ma być traktowany jako część aplikacji jednostronicowej. Jeśli obie opcje navigateFallbackDenylist i navigateFallbackAllowlist są skonfigurowane, lista zaprzeczeń ma pierwszeństwo.

    Uwaga: podczas nawigacji te wyrażenia regularne mogą być oceniane na podstawie każdego adresu URL docelowego. Unikaj korzystania z złożonych wyrażeń regularnych, ponieważ może to spowodować opóźnienia w nawigacji po witrynie.

  • navigationPreload

    Wartość logiczna opcjonalna

    Wartość domyślna: false

    Określa, czy w wygenerowanym serwisie workera ma być włączone wstępnie wczytywanie nawigacji. Gdy ta opcja jest ustawiona na wartość true, musisz też użyć opcji runtimeCaching, aby skonfigurować odpowiednią strategię odpowiedzi, która będzie pasować do żądań nawigacji, i korzystać z wstępnie załadowanej odpowiedzi.

  • offlineGoogleAnalytics

    boolean | GoogleAnalyticsInitializeOptions opcjonalna.

    Wartość domyślna: false

    Określa, czy obsługiwać Google Analytics offline. Gdy true, wywołanie metody initialize() użytkownika workbox-google-analytics zostanie dodane do wygenerowanego skryptu service worker. Gdy ustawisz wartość Object, ten obiekt zostanie przekazany do wywołania initialize(), co pozwoli Ci dostosować działanie.

  • runtimeCaching

    RuntimeCaching[] opcjonalne

    Jeśli do generowania skryptu service workbox używasz narzędzi do kompilacji Workbox, możesz określić co najmniej 1 konfigurację buforowania środowiska wykonawczego. Następnie są one tłumaczone na 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ę z 2 zdefiniowanymi ścieżkami w czasie wykonywania:

  • skipWaiting

    Wartość logiczna opcjonalna

    Wartość domyślna to false.

    Określa, czy do wygenerowanego service workera ma zostać dodane bezwarunkowe wywołanie skipWaiting(). Jeśli false, zamiast tego zostanie dodany odbiorca message, co pozwoli stronom klienta wywoływać skipWaiting() przez wywołanie postMessage({type: 'SKIP_WAITING'}) w ramach oczekującego wątku usługi.

  • mapa źródłowa

    logiczna opcjonalna

    Wartość domyślna: true.

    Określa, czy dla wygenerowanych plików service workera ma zostać utworzony plik mapy źródeł.

  • swDest

    ciąg znaków opcjonalny

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

    Nazwa zasobu pliku usługi roboczej utworzonego przez tę wtyczkę.

InjectManifest

Ta klasa obsługuje kompilowanie pliku usługi udostępnianego za pomocą swSrc oraz wstrzykiwanie do tego pliku usługi listy adresów URL i informacji o rewizji na potrzeby wstępnego buforowania na podstawie potoku zasobów 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 internetowego.

// 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

Właściwości

default

Typ

Obiekt

Właściwości

  • GenerateSW

    zapytanie

  • InjectManifest

    zapytanie