precaching van werkvakken

Eén kenmerk van servicemedewerkers is de mogelijkheid om een ​​reeks bestanden in de cache op te slaan wanneer de servicemedewerker aan het installeren is. Dit wordt vaak 'precaching' genoemd, omdat u inhoud in de cache opslaat voordat de servicemedewerker wordt gebruikt.

De belangrijkste reden hiervoor is dat het ontwikkelaars controle geeft over de cache, wat betekent dat ze kunnen bepalen wanneer en hoe lang een bestand in de cache wordt opgeslagen en dat ze dit aan de browser kunnen doorgeven zonder naar het netwerk te gaan, wat betekent dat het kan worden gebruikt om webbestanden te maken. apps die offline werken.

Workbox neemt een groot deel van het zware werk uit precaching weg door de API te vereenvoudigen en ervoor te zorgen dat assets efficiënt worden gedownload.

Hoe werkbox-precaching werkt

Wanneer een webapp voor de eerste keer wordt geladen, kijkt workbox-precaching naar alle assets die u wilt downloaden, verwijdert eventuele duplicaten en koppelt de relevante servicemedewerkergebeurtenissen aan om de assets te downloaden en op te slaan. URL's die al versie-informatie bevatten (zoals een inhoudshash) worden zonder verdere wijzigingen als cachesleutels gebruikt. URL's die geen versiegegevens bevatten, hebben een extra URL-queryparameter toegevoegd aan hun cachesleutel die een hash van hun inhoud vertegenwoordigt die Workbox tijdens de build genereert.

workbox-precaching doet dit allemaal tijdens de install van de servicewerker.

Wanneer een gebruiker uw web-app later opnieuw bezoekt en u een nieuwe servicemedewerker heeft met verschillende vooraf in de cache opgeslagen activa, zal workbox-precaching naar de nieuwe lijst kijken en bepalen welke activa volledig nieuw zijn en welke van de bestaande activa moeten worden bijgewerkt, op basis van hun revisie. Eventuele nieuwe assets of bijgewerkte revisies worden aan de cache toegevoegd tijdens de install van de nieuwe servicemedewerker.

Deze nieuwe servicemedewerker wordt pas gebruikt om op aanvragen te reageren nadat de activate is geactiveerd. Het is in de activate dat workbox-precaching controleert of er in de cache opgeslagen assets zijn die niet langer aanwezig zijn in de lijst met huidige URL's, en deze uit de cache verwijdert.

workbox-precaching voert deze stappen uit elke keer dat uw servicemedewerker wordt geïnstalleerd en geactiveerd, zodat de gebruiker over de nieuwste assets beschikt en alleen de gewijzigde bestanden worden gedownload.

Vooraf in de cache opgeslagen antwoorden weergeven

Door precacheAndRoute() of addRoute() aan te roepen, wordt een route gemaakt die overeenkomt met verzoeken voor vooraf in de cache opgeslagen URL's.

De responsstrategie die bij deze route wordt gebruikt, is cache-first : het vooraf in de cache opgeslagen antwoord zal worden gebruikt, tenzij dat in het cachegeheugen opgeslagen antwoord niet aanwezig is (vanwege een onverwachte fout), in welk geval in plaats daarvan een netwerkantwoord zal worden gebruikt.

De volgorde waarin u precacheAndRoute() of addRoute() aanroept, is belangrijk. Normaal gesproken wilt u dit al vroeg in uw servicewerknemersbestand aanroepen, voordat u extra routes registreert met registerRoute() . Als u eerst registerRoute() hebt aangeroepen en die route overeenkomt met een inkomend verzoek, wordt de strategie die u in die extra route hebt gedefinieerd, gebruikt om te reageren, in plaats van de cache-first-strategie die wordt gebruikt door workbox-precaching .

Uitleg van de Precache-lijst

workbox-precaching verwacht een array van objecten met een url en revision eigenschap. Deze array wordt soms een precache-manifest genoemd:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([
  {url: '/index.html', revision: '383676'},
  {url: '/styles/app.0c9a31.css', revision: null},
  {url: '/scripts/app.0d5770.js', revision: null},
  // ... other entries ...
]);

Deze lijst verwijst naar een reeks URL's, elk met hun eigen stukje "revisie"-informatie.

Voor het tweede en derde object in het bovenstaande voorbeeld is de eigenschap revision ingesteld op null . Dit komt omdat de revisie-informatie zich in de URL zelf bevindt , wat over het algemeen een best practice is voor statische items.

Het eerste object ( /index.html ) stelt expliciet een revisie-eigenschap in, wat een automatisch gegenereerde hash is van de inhoud van het bestand. In tegenstelling tot JavaScript- en CSS-bronnen kunnen HTML-bestanden over het algemeen geen revisie-informatie in hun URL's opnemen, anders zouden links naar deze bestanden op internet kapot gaan telkens wanneer de inhoud van de pagina verandert.

Door een revisie-eigenschap door te geven aan precacheAndRoute() , kan Workbox weten wanneer het bestand is gewijzigd en het dienovereenkomstig bijwerken.

Workbox wordt geleverd met hulpmiddelen die u kunnen helpen bij het genereren van deze lijst:

• workbox-build : dit is een knooppuntpakket dat kan worden gebruikt in een gulp-taak of als een npm-run-script.
• workbox-webpack-plugin : webpack-gebruikers kunnen deze plug-in gebruiken.
• workbox-cli : Onze CLI kan ook worden gebruikt om de lijst met activa te genereren en deze toe te voegen aan uw servicemedewerker.

Inkomende verzoeken voor vooraf in de cache opgeslagen bestanden

Eén ding dat workbox-precaching kant-en-klaar zal doen, is het manipuleren van de binnenkomende netwerkverzoeken om te proberen vooraf in de cache opgeslagen bestanden te matchen. Dit biedt ruimte voor gangbare praktijken op internet.

Aan een verzoek om / kan bijvoorbeeld meestal worden voldaan door het bestand /index.html .

Hieronder vindt u de lijst met manipulaties die workbox-precaching standaard uitvoert, en hoe u dat gedrag kunt wijzigen.

Negeer URL-parameters

Verzoeken met zoekparameters kunnen worden gewijzigd om specifieke waarden te verwijderen, of om alle waarden te verwijderen.

Standaard worden zoekparameters die beginnen met utm_ of exact overeenkomen met fbclid verwijderd, wat betekent dat een verzoek voor /about.html?utm_campaign=abcd zal worden vervuld met een vooraf in de cache opgeslagen vermelding voor /about.html .

U kunt een andere set zoekparameters negeren met behulp van ignoreURLParametersMatching :

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    // Ignore all URL parameters.
    ignoreURLParametersMatching: [/.*/],
  }
);

Directory-index

Verzoeken die eindigen op een / worden standaard vergeleken met vermeldingen met een index.html aan het einde. Dit betekent dat een binnenkomend verzoek voor / automatisch kan worden afgehandeld met de vooraf in de cache opgeslagen vermelding /index.html .

Je kunt dit in iets anders veranderen, of volledig uitschakelen, door directoryIndex in te stellen:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    directoryIndex: null,
  }
);

Schone URL's

Als een verzoek niet overeenkomt met de precache, voegen we .html toe aan het einde om 'schone' URL's (ook wel 'mooie' URL's genoemd) te ondersteunen. Dit betekent dat een verzoek als /about wordt afgehandeld door de vooraf in de cache opgeslagen vermelding voor /about.html .

U kunt dit gedrag uitschakelen door cleanUrls in te stellen:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([{url: '/about.html', revision: 'b79cd4'}], {
  cleanUrls: false,
});

Aangepaste manipulaties

Als u aangepaste overeenkomsten wilt definiëren tussen inkomende verzoeken en vooraf in de cache opgeslagen assets, kunt u dit doen met de optie urlManipulation . Dit zou een callback moeten zijn die een reeks mogelijke overeenkomsten retourneert.

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    urlManipulation: ({url}) => {
      // Your logic goes here...
      return [alteredUrlOption1, alteredUrlOption2];
    },
  }
);

Geavanceerd gebruik

PrecacheController rechtstreeks gebruiken

Standaard zal workbox-precaching de install instellen en luisteraars voor u activate . Voor ontwikkelaars die bekend zijn met servicemedewerkers is dit misschien niet wenselijk als je meer controle nodig hebt.

In plaats van de standaardexport te gebruiken, kunt u de PrecacheController rechtstreeks gebruiken om items aan de precache toe te voegen, te bepalen wanneer deze assets worden geïnstalleerd en wanneer het opruimen moet plaatsvinden.

import {PrecacheController} from 'workbox-precaching';

const precacheController = new PrecacheController();
precacheController.addToCacheList([
  {url: '/styles/example-1.abcd.css', revision: null},
  {url: '/styles/example-2.1234.css', revision: null},
  {url: '/scripts/example-1.abcd.js', revision: null},
  {url: '/scripts/example-2.1234.js', revision: null},
]);

precacheController.addToCacheList([{
  url: '/index.html',
  revision: 'abcd',
}, {
  url: '/about.html',
  revision: '1234',
}]);

self.addEventListener('install', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.install(event));
});

self.addEventListener('activate', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.activate(event));
});

self.addEventListener('fetch', (event) => {
  const cacheKey = precacheController.getCacheKeyForURL(event.request.url);
  event.respondWith(caches.match(cacheKey).then(...));
});

Vooraf in de cache opgeslagen activa rechtstreeks lezen

Er zijn momenten waarop u een vooraf in de cache opgeslagen asset rechtstreeks moet lezen, buiten de context van de routering die door workbox-precaching automatisch kan worden uitgevoerd. U wilt bijvoorbeeld gedeeltelijke HTML-sjablonen vooraf in de cache opslaan, die vervolgens moeten worden opgehaald en gebruikt bij het samenstellen van een volledig antwoord.

Over het algemeen kunt u de Cache Storage API gebruiken om de vooraf in de cache opgeslagen Response objecten te verkrijgen, maar er is één probleem: de URL-cachesleutel die moet worden gebruikt bij het aanroepen van cache.match() kan een versieparameter bevatten die door workbox-precaching automatisch wordt gemaakt en onderhoudt.

Om de juiste cachesleutel te verkrijgen, kunt u getCacheKeyForURL() aanroepen, de originele URL doorgeven en vervolgens het resultaat gebruiken om een cache.match() uit te voeren op de juiste cache.

import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';

const cache = await caches.open(cacheNames.precache);
const response = await cache.match(getCacheKeyForURL('/precached-file.html'));

Als alternatief, als u alleen het vooraf in de cache opgeslagen Response object nodig heeft, kunt u matchPrecache() aanroepen, waardoor automatisch de juiste cachesleutel wordt gebruikt en in de juiste cache wordt gezocht:

import {matchPrecache} from 'workbox-precaching';

const response = await matchPrecache('/precached-file.html');

Oude precaches opruimen

De meeste releases van Workbox behouden hetzelfde formaat voor het opslaan van vooraf in de cache opgeslagen gegevens, en precaches die door oudere versies van Workbox zijn gemaakt, kunnen normaal gesproken ongewijzigd worden gebruikt door nieuwere releases. Zelden is er echter sprake van een ingrijpende verandering in de precaching-opslag, waardoor bestaande gebruikers alles opnieuw moeten downloaden en waardoor eerder geprecached gegevens overbodig worden. (Een dergelijke verandering vond plaats tussen de releases van Workbox v3 en v4.)

Deze verouderde gegevens mogen de normale werking niet verstoren, maar dragen wel bij aan uw algehele gebruik van opslagquota, en het kan vriendelijker zijn voor uw gebruikers om deze expliciet te verwijderen. U kunt dit doen door cleanupOutdatedCaches() toe te voegen aan uw servicemedewerker, of door cleanupOutdatedCaches: true in te stellen als u een van de buildtools van Workbox gebruikt om uw servicemedewerker te genereren.

Integriteit van subbronnen gebruiken

Sommige ontwikkelaars willen mogelijk de extra garanties die worden geboden door de handhaving van de integriteit van subresources bij het ophalen van vooraf in de cache opgeslagen URL's van het netwerk.

Een extra, optionele eigenschap genaamd integrity kan worden toegevoegd aan elk item in het precache-manifest. Indien opgegeven, wordt deze gebruikt als de integrity bij het samenstellen van de Request die wordt gebruikt om de cache te vullen. Als er een mismatch is, mislukt het precachingproces.

Het bepalen welke precache-manifestitems integrity moeten hebben, en het uitzoeken van de juiste waarden om te gebruiken, valt buiten het bereik van de buildtools van Workbox. In plaats daarvan moeten ontwikkelaars die zich willen aanmelden voor deze functionaliteit het precache-manifest dat Workbox genereert aanpassen om zelf de juiste informatie toe te voegen. De optie manifestTransform in de configuratie van de buildtools van Workbox kan helpen:

const ssri = require('ssri');

const integrityManifestTransform = (originalManifest, compilation) => {
  const warnings = [];
  const manifest = originalManifest.map(entry => {
    // If some criteria match:
    if (entry.url.startsWith('...')) {
      // This has to be a synchronous function call, for example:
      // compilation will be set when using workbox-webpack-plugin.
      // When using workbox-build directly, you can read the file's
      // contents from disk using, e.g., the fs module.
      const asset = compilation.getAsset(entry.url);
      entry.integrity = ssri.fromData(asset.source.source()).toString();

      // Push a message to warnings if needed.
    }
    return entry;
  });

  return {warnings, manifest};
};

// Then add manifestTransform: [integrityManifestTransform]
// to your Workbox build configuration.

workbox-precaching.urlManipulation(
  { url }: object,
)

workbox-precaching.addPlugins(
  plugins: WorkboxPlugin[],
)

workbox-precaching.addRoute(
  options?: PrecacheRouteOptions,
)

workbox-precaching.cleanupOutdatedCaches()

workbox-precaching.createHandlerBoundToURL(
  url: string,
)

workbox-precaching.getCacheKeyForURL(
  url: string,
)

workbox-precaching.matchPrecache(
  request: string | Request,
)

workbox-precaching.precache(
  entries: (string | PrecacheEntry)[],
)

workbox-precaching.precacheAndRoute(
  entries: (string | PrecacheEntry)[],
  options?: PrecacheRouteOptions,
)