Esta guía se enfoca en los cambios rotundos que se introdujeron en Workbox v4, con ejemplos de los cambios que deberías realizar cuando actualices desde Workbox v3.
Cambios rotundos
workbox-precaching
Se actualizó la convención de nombres para las entradas almacenadas en caché previamente. Ahora, para las entradas cuyas URLs necesitan información de revisión (es decir, aquellas que contienen un campo revision en el manifiesto de almacenamiento en caché anticipado), esa información de control de versiones se almacenará como parte de la clave de caché, en un parámetro de consulta de URL __WB_REVISION__ especial que se agregará a la URL original. (Anteriormente, esta información se almacenaba por separado de las claves de caché con 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 realizar ningún cambio en la configuración de su service worker. Cuando actualicen a Workbox v4, los recursos almacenados en caché de tus usuarios migrarán automáticamente al nuevo formato de clave de caché y, de ahora en adelante, los recursos almacenados en caché previamente se seguirán entregando de la misma manera que antes.
Cómo usar claves de caché directamente
Es posible que algunos desarrolladores deban acceder a las entradas de almacenamiento en caché directamente, fuera del contexto de workbox.precaching.precacheAndRoute(). Por ejemplo, puedes almacenar en caché previamente una imagen que termines usando como respuesta de "reemplazo" cuando no se pueda recuperar una imagen real de la red.
Si usas recursos almacenados en caché de esta manera, a partir de Workbox v4, deberás realizar un paso adicional para traducir una URL original en 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' está almacenado en caché previamente, 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 previamente en caché
Los cambios realizados en el almacenamiento en caché previo en Workbox v4 implican que los almacenamientos en caché anteriores, creados por versiones anteriores de Workbox, no son compatibles. De forma predeterminada, se dejan como están y, si actualizas de Workbox v3 a Workbox v4, obtendrás dos copias de todos tus recursos almacenados en caché previamente.
Para evitar esto, puedes agregar la llamada a workbox.precaching.cleanupOutdatedCaches() directamente a un trabajador de servicio o establecer la nueva opción cleanupOutdatedCaches: true si usas una herramienta de compilación en modo GenerateSW. Debido a que la lógica de limpieza de la caché opera en convenciones de nombres de caché para encontrar cachés previas más antiguas y a que los desarrolladores tienen la opción de anular esas convenciones, nos decantamos por la seguridad y no habilitamos esta opción de forma predeterminada.
Recomendamos a los desarrolladores que tengan algún problema al usar esta función, como falsos positivos en relación con la eliminación, que se comuniquen con nosotros.
Capitalización de parámetros
Se cambiaron los nombres 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.
workbox-strategies
Existen dos formas aproximadamente equivalentes de crear una instancia de un controlador en workbox-strategies. Daremos de baja el método de fábrica y, en su lugar, llamaremos explícitamente 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 versión 5 futura.
workbox-background-sync
La clase workbox.backgroundSync.Queue se volvió a escribir 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 v3, la clase Queue tenía una sola manera 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 arrays:
pushRequest()popRequest()shiftRequest()unshiftRequest()
En la v3, la clase Queue también aceptaba varias devoluciones de llamada que te permitían observar cuándo se repetían las solicitudes (requestWillEnqueue, requestWillReplay, queueDidReplay). Sin embargo, la mayoría de los desarrolladores descubrieron que, además de la observación, querían controlar cómo se repetía la cola, incluida la capacidad de modificar, reordenar o incluso cancelar solicitudes individuales de forma dinámica.
En la v4, se quitaron estas devoluciones de llamada para favorecer 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á replayRequests(), pero si necesitas más control sobre el proceso de repetición, puedes usar los métodos similares a arrays que se enumeraron anteriormente para volver a reproducir la fila como desees.
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.
workbox-expiration
Se cambió el nombre del paquete npm por workbox-expiration, que coincide con la convención de nomenclatura que se usa para otros módulos. Este paquete es funcionalmente equivalente al paquete workbox-cache-expiration anterior, que ahora dejó de estar disponible.
workbox-broadcast-update
Se cambió el nombre del paquete npm por workbox-broadcast-update, que coincide con la convención de nomenclatura que se usa para otros módulos. Este paquete es funcionalmente equivalente al paquete workbox-broadcast-cache-update anterior, que ahora dejó de estar disponible.
workbox-core
En Workbox v3, la verbosidad de los niveles de registro se podía controlar con el método workbox.core.setLogLevel(), al que pasarías uno de los valores de la enum 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 todos estos elementos, ya que todas las herramientas para desarrolladores modernas ahora se envían con capacidades de filtrado de registros enriquecidos (consulta cómo filtrar la salida de la consola en las Herramientas para desarrolladores de Chrome).
workbox-sw
En su lugar, se trasladaron a workbox.core los dos métodos que 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 la herramienta 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 usaba "Url" en el nombre de una opción, se daba de baja en favor de "URL". Esto significa que se prefieren los siguientes nombres de opciones:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
La variación "Url" de esos nombres de opciones aún funciona en la versión 4, pero se mostrará un mensaje de advertencia. Recomendamos a los desarrolladores que migren antes de la versión v5.
Nuevas funciones
workbox-window
El nuevo módulo workbox-window simplifica el proceso de registro del trabajador de servicio y la detección de actualizaciones, y proporciona un medio de comunicación estándar entre el código que se ejecuta en el trabajador de servicio y el código que se ejecuta en el contexto window de tu app web.
Si bien usar workbox-window es opcional, esperamos que los desarrolladores lo encuentren útil y consideren migrar parte de su lógica escrita a mano para usarlo cuando corresponda. Puedes obtener más información para usar workbox-window en la guía del módulo.
Ejemplo de migración
Puedes encontrar un ejemplo de una migración en el mundo real de Workbox v3 a v4 en esta solicitud de extracción.
Cómo obtener ayuda
Prevemos que la mayoría de las migraciones sean sencillas. Si tienes problemas que no se abordan en esta guía, abre un problema en GitHub para informarnos al respecto.