Esta guía se centra en los cambios rotundos que se introdujeron en Workbox v4, con ejemplos de los cambios que deberías hacer al actualizar desde Workbox v3.
Cambios rotundos
almacenamiento en caché de la caja de trabajo
Se actualizó la convención de nombres para las entradas almacenadas previamente en caché. Ahora, para las entradas cuyas URLs necesitan información de revisión (es decir, las entradas que contienen un campo revision en el manifiesto de almacenamiento previo en caché), esa información de control de versiones se almacenará como parte de la clave de caché, en un parámetro de consulta de URL especial __WB_REVISION__ anexado a la URL original. (Anteriormente, esta información se almacenaba por separado de las claves de caché mediante IndexedDB).
Los desarrolladores que aprovechan el almacenamiento previo en caché a través de workbox.precaching.precacheAndRoute(), que es el caso de uso más común, no necesitan hacer ningún cambio en la configuración de su service worker. Después de actualizar a Workbox v4, los elementos almacenados en caché de los usuarios migrarán automáticamente al nuevo formato de clave de caché y, de ahora en más, los recursos almacenados previamente en caché seguirán entregando de la misma manera que antes.
Uso directo de claves de caché
Es posible que algunos desarrolladores necesiten acceder a las entradas de precaché directamente, fuera del contexto de workbox.precaching.precacheAndRoute(). Por ejemplo, puedes almacenar previamente en caché una imagen que termines usando como respuesta de "resguardo" cuando no se pueda recuperar una imagen real de la red.
Si usas recursos prealmacenados en caché de esta manera, a partir de Workbox v4, deberás realizar un paso adicional para traducir una URL original a la clave de caché correspondiente que se puede usar para leer la entrada almacenada en caché. Para ello, llama a workbox.precaching.getCacheKeyForURL(originURL).
Por ejemplo, si sabes que 'fallback.png' se prealmacena en caché, haz lo siguiente:
const imageFallbackCacheKey =
workbox.precaching.getCacheKeyForURL('fallback.png');
workbox.routing.setCatchHandler(({event}) => {
switch (event.request.destination) {
case 'image':
return caches.match(imageFallbackCacheKey);
break;
// ...other fallback logic goes here...
}
});
Limpia datos antiguos almacenados en caché previamente
Debido a los cambios en el almacenamiento previo en caché de Workbox v4, los precachés anteriores, creados por versiones anteriores de Workbox, no son compatibles. De forma predeterminada, no se modifican, y si actualizas de Workbox v3 a Workbox v4, obtendrás dos copias de todos los recursos almacenados en caché previamente.
Para evitar esto, puedes agregar la llamada a workbox.precaching.cleanupOutdatedCaches() directamente a un service worker o configurar la nueva opción cleanupOutdatedCaches: true si usas una herramienta de compilación en el modo GenerateSW. Debido a que la lógica de limpieza de caché opera en convenciones de nomenclatura de caché para encontrar precachés más antiguas, y debido a que los desarrolladores tienen la opción de anular esas convenciones, nos equivocamos por un lado de la seguridad y no habilitamos esto de forma predeterminada.
Recomendamos a los desarrolladores que tengan algún problema al usar esta función (como falsos positivos sobre la eliminación) que nos informen al respecto.
Uso de mayúsculas en los parámetros
Se cambió el nombre de dos parámetros opcionales que se pueden pasar a workbox.precaching.precacheAndRoute() y workbox.precaching.addRoute() para estandarizar nuestra convención general de mayúsculas. ignoreUrlParametersMatching ahora es ignoreURLParametersMatching, y cleanUrls ahora es cleanURLs.
Estrategias de cuadros de trabajo
Hay dos formas aproximadamente equivalentes de crear una instancia de un controlador en workbox-strategies. El método de fábrica dejará de estar disponible para llamar de forma explícita al constructor de la estrategia.
// This factory method syntax has been deprecated:
const networkFirstStrategy = workbox.strategies.networkFirst({...});
// Instead, use the constructor directly:
// (Note that the class name is Uppercase.)
const networkFirstStrategy = new workbox.strategies.NetworkFirst({...});
Si bien la sintaxis del método de fábrica seguirá funcionando en la versión 4, su uso registrará una advertencia, y recomendamos a los desarrolladores que migren antes de quitar la compatibilidad en la futura versión 5.
sincronización en segundo plano de la caja de trabajo
Se reescribió la clase workbox.backgroundSync.Queue para ofrecer a los desarrolladores más flexibilidad y control sobre cómo se agregan las solicitudes a la cola y se vuelven a reproducir.
En la versión 3, la clase Queue tenía una sola forma de agregar solicitudes a la cola (el método addRequest()), pero no tenía ninguna manera de modificar la cola ni quitar solicitudes.
En la versión 4, se quitó el método addRequests() y se agregaron los siguientes métodos similares a un array:
pushRequest()popRequest()shiftRequest()unshiftRequest()
En la versión 3, la clase Queue también aceptaba varias devoluciones de llamada que te permiten observar cuándo se vuelven a reproducir las solicitudes (requestWillEnqueue, requestWillReplay y queueDidReplay), pero la mayoría de los desarrolladores descubrió que, además de la observación, querían controlar cómo se reproducía la cola, incluida la capacidad de modificar, reordenar o incluso cancelar solicitudes individuales de forma dinámica.
En la versión 4, estas devoluciones de llamada se quitaron para dar lugar a una sola devolución de llamada onSync, que se invoca cada vez que el navegador realiza un intento de repetición. De forma predeterminada, la devolución de llamada onSync invocará a replayRequests(), pero si necesitas más control sobre el proceso de repetición, puedes usar los métodos similares a un array que se mencionaron anteriormente para reproducir la cola como quieras.
Este es un ejemplo de lógica de repetición personalizada:
const queue = new workbox.backgroundSync.Queue('my-queue-name', {
onSync: async ({queue}) => {
let entry;
while ((entry = await this.shiftRequest())) {
try {
await fetch(entry.request);
} catch (error) {
console.error('Replay failed for request', entry.request, error);
await this.unshiftRequest(entry);
return;
}
}
console.log('Replay complete!');
},
});
De manera similar, la clase workbox.backgroundSync.Plugin acepta los mismos argumentos que la clase Queue (ya que crea una instancia Queue internamente), por lo que cambió de la misma manera.
vencimiento del cuadro de trabajo
Se cambió el nombre del paquete npm a workbox-expiration, que coincide con la convención de nombres que se usa para otros módulos. En términos funcionales, este paquete es equivalente al paquete workbox-cache-expiration anterior, que dejó de estar disponible.
Actualización-de-transmisión-de-la-caja de trabajo
Se cambió el nombre del paquete npm a workbox-broadcast-update, que coincide con la convención de nombres que se usa para otros módulos. En términos funcionales, este paquete es equivalente al paquete workbox-broadcast-cache-update anterior, que dejó de estar disponible.
núcleo-caja de trabajo
En Workbox v3, la verbosidad de los niveles de registro se puede controlar con el método workbox.core.setLogLevel(), al que se debe pasar uno de los valores de la enumeración workbox.core.LOG_LEVELS. También puedes leer el nivel de registro actual a través de workbox.core.logLevel.
En Workbox v4, se quitaron todas estas opciones, ya que todas las herramientas modernas para desarrolladores ahora incluyen funciones enriquecidas de filtrado de registros (consulta cómo filtrar el resultado de la consola para las herramientas para desarrolladores de Chrome).
Workbox-sw
En su lugar, se movieron a workbox.core dos métodos que antes se expusieron directamente en el espacio de nombres workbox (que corresponde al módulo workbox-sw). workbox.skipWaiting() se convirtió en workbox.core.skipWaiting() y, de manera similar, workbox.clientsClaim() se convirtió en workbox.core.clientsClaim().
Configuración de herramientas de compilación
Cambió la denominación de algunas opciones que se pueden pasar a workbox-cli, workbox-build o workbox-webpack-plugin. Cuando se usa "Url" en el nombre de una opción, deja de estar disponible y se reemplaza por "URL". Esto significa que se prefieren los siguientes nombres de opciones:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
La variación "Url" de esos nombres de opción aún funciona en la versión 4, pero generará un mensaje de advertencia. Recomendamos a los desarrolladores que realicen la migración antes de la versión v5.
Nueva funcionalidad
Ventana del cuadro de trabajo
El nuevo módulo workbox-window simplifica el proceso de registro y detección de actualizaciones de service worker, y proporciona un medio de comunicación estándar entre el código que se ejecuta en el service worker y el código que se ejecuta en el contexto de window de tu app web.
Si bien el uso de workbox-window es opcional, esperamos que los desarrolladores les resulte útil y consideren migrar parte de su lógica escrita a mano para usarla cuando corresponda. Puedes obtener más información para usar workbox-window en la guía del módulo.
Ejemplo de migración
En esta solicitud de extracción, se puede encontrar un ejemplo de una migración real de Workbox v3 a v4.
Cómo obtener ayuda
Prevemos que la mayoría de las migraciones serán sencillas. Si tienes problemas que no se tratan en esta guía, abre un problema en GitHub para informarnos al respecto.