Workbox proporciona dos complementos webpack: uno que genera un service worker completo y otro que genera una lista de elementos que se almacenan previamente en caché y se insertan en un archivo de service worker.
Los complementos se implementan como dos clases en el módulo workbox-webpack-plugin
, denominadas GenerateSW
y InjectManifest
. Las respuestas a las siguientes preguntas pueden ayudarte a elegir el complemento y la configuración correctos para usar.
Qué complemento usar
GenerateSW
El complemento GenerateSW
creará un archivo de service worker y lo agregará a la canalización de recursos del paquete web.
Cuándo usar GenerateSW
- Deseas almacenar archivos en caché previamente.
- Tienes necesidades de almacenamiento en caché de entorno de ejecución simples.
Cuándo NO usar GenerateSW
- Deseas usar otras funciones de Service Worker (es decir, Web Push).
- Quieres importar secuencias de comandos adicionales o agregar lógica adicional para estrategias personalizadas de almacenamiento en caché.
InjectManifest
El complemento InjectManifest
generará una lista de URLs para almacenar en caché y agregará ese manifiesto de almacenamiento previo a un archivo de service worker existente. De lo contrario, el archivo quedará como está.
Cuándo usar InjectManifest
- Quieres tener más control sobre tu service worker.
- Deseas almacenar archivos en caché previamente.
- Debes personalizar el enrutamiento y las estrategias.
- Quieres usar tu service worker con otras funciones de la plataforma (por ejemplo, Web Push).
Cuándo NO usar InjectManifest
- Quieres la ruta más fácil para agregar un service worker a tu sitio.
Complemento GenerateSW
Puedes agregar el complemento GenerateSW
a la configuración de tu webpack de la siguiente manera:
// 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: ...,
}),
],
};
Esto generará un service worker con configuración de almacenamiento previo en caché para todos los recursos de webpack que recogió tu configuración y las reglas de almacenamiento en caché del entorno de ejecución proporcionadas.
Puedes encontrar un conjunto completo de opciones de configuración en la documentación de referencia.
Complemento de InjectManifest
Puedes agregar el complemento InjectManifest
a la configuración de tu webpack de la siguiente manera:
// 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: '...',
}),
],
};
De esta forma, se creará un manifiesto de precaché basado en los recursos de webpack recogido por tu configuración y se insertará en tu archivo de service worker empaquetado y compilado.
Puedes encontrar un conjunto completo de opciones de configuración en la documentación de referencia.
Información adicional
Puedes encontrar orientación sobre el uso de los complementos en el contexto de una compilación de webpack más grande en la sección "Aplicación web progresiva" de la documentación de webpack.
Tipos
GenerateSW
Esta clase admite la creación de un archivo de service worker nuevo y listo para usar como parte del proceso de compilación de webpack.
Usa una instancia de GenerateSW
en el array plugins
de una configuración de webhook.
// 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: ...,
});
Propiedades
-
constructor
void
Crea una instancia de GenerateSW.
La función
constructor
se ve de la siguiente manera:(config?: GenerateSWConfig) => {...}
-
config
GenerateSWConfig opcional
-
resultados
-
-
config
GenerateSWConfig
Propiedades
-
additionalManifestEntries
(string | ManifestEntry)[] opcional
Una lista de entradas que se almacenarán en caché, además de las entradas que se generen como parte de la configuración de compilación.
-
babelPresetEnvTargets
string[] opcional
El valor predeterminado es: ["chrome >= 56"]
Los objetivos que se pasarán a
babel-preset-env
cuando se transpila el paquete de service worker. -
cacheId
cadena opcional
Un ID opcional que se antepone a los nombres de la caché. Esto es útil principalmente para el desarrollo local en el que se pueden entregar varios sitios desde el mismo origen
http://localhost:port
. -
fragmentos
string[] opcional
Uno o más nombres de fragmento cuyos archivos de salida correspondientes se deben incluir en el manifiesto de precaché.
-
cleanupOutdatedCaches
booleano opcional
El valor predeterminado es false
Indica si Workbox debe intentar identificar y borrar las cachés previas creadas por versiones incompatibles y anteriores.
-
clientsClaim
booleano opcional
El valor predeterminado es false
Indica si el service worker debe comenzar a controlar los clientes existentes en cuanto se activa.
-
directoryIndex
cadena opcional
Si una solicitud de navegación para una URL que termina en
/
no coincide con una URL previamente almacenada en caché, este valor se agregará a la URL y se verificará si hay una coincidencia. Esto se debe configurar como lo que usa tu servidor web para el índice del directorio. -
disableDevLogs
booleano opcional
El valor predeterminado es false
-
dontCacheBustURLsMatching
RegExp opcional
Se considerará que los recursos que coinciden con esto tienen control de versiones de forma única a través de su URL y están exentos de la prevención del almacenamiento en caché de HTTP normal que se produce cuando se propaga el almacenamiento previo en caché. Si bien no es obligatorio, te recomendamos que, si tu proceso de compilación existente ya inserta un valor
[hash]
en cada nombre de archivo, proporciones una expresión regular que detecte eso, ya que reducirá el ancho de banda consumido cuando se almacena en caché previamente. -
excluir
(string | RegExp | function)[] opcional
Uno o más especificadores que se usan para excluir recursos del manifiesto de precaché. Esto se interpreta siguiendo las mismas reglas que la opción
exclude
estándar dewebpack
. Si no se proporciona, el valor predeterminado es[/\.map$/, /^manifest.*\.js$]
. -
excludeChunks
string[] opcional
Uno o más nombres de fragmento cuyos archivos de salida correspondientes deben excluirse del manifiesto de precaché.
-
ignoreURLParametersMatching
RegExp[] opcional
Cualquier nombre de parámetro de búsqueda que coincida con una de las expresiones regulares de este array se quitará antes de buscar una coincidencia en caché previa. Esto es útil si tus usuarios pueden solicitar URLs que contienen, por ejemplo, parámetros de URL que se usan para realizar un seguimiento del origen del tráfico. Si no se proporciona, el valor predeterminado es
[/^utm_/, /^fbclid$/]
. -
importScripts
string[] opcional
Una lista de archivos JavaScript que se deben pasar a
importScripts()
dentro del archivo de service worker generado. Resulta útil cuando quieres permitir que Workbox cree tu archivo de service worker de nivel superior, pero quieres incluir código adicional, como un objeto de escucha de eventos push. -
importScriptsViaChunks
string[] opcional
Uno o más nombres de fragmentos de webpack. El contenido de esos fragmentos se incluirá en el service worker generado mediante una llamada a
importScripts()
. -
incluye
(string | RegExp | function)[] opcional
Uno o más especificadores que se usan para incluir recursos en el manifiesto de precaché. Esto se interpreta siguiendo las mismas reglas que la opción
include
estándar dewebpack
. -
inlineWorkboxRuntime
booleano opcional
El valor predeterminado es false
Define si el código del entorno de ejecución para la biblioteca de Workbox debe incluirse en el service worker de nivel superior o dividirse en un archivo separado que se deba implementar junto con el service worker. Mantener el entorno de ejecución separado significa que los usuarios no tendrán que volver a descargar el código de Workbox cada vez que cambie el service worker de nivel superior.
-
manifestEntries
ManifestEntry[] opcional
-
manifestTransforms
ManifestTransform[] opcional
Una o más funciones que se aplicarán de forma secuencial en el manifiesto generado. Si también se especifican
modifyURLPrefix
odontCacheBustURLsMatching
, las transformaciones correspondientes se aplicarán primero. -
maximumFileSizeToCacheInBytes
número opcional
El valor predeterminado es 2097152.
Este valor se puede usar para determinar el tamaño máximo de los archivos que se almacenarán en caché previamente. De esta manera, se evita almacenar en caché previamente sin querer archivos muy grandes que podrían haber coincidido accidentalmente con uno de tus patrones.
-
Standard
cadena opcional
Si se configura como “production”, se generará un paquete de service worker optimizado que excluya la información de depuración. Si no se configura explícitamente aquí, se usará el valor
mode
configurado en la compilación actual dewebpack
. -
modifyURLPrefix
objeto opcional
Un objeto que asigna prefijos de cadena para reemplazar valores de cadena. Se puede usar para, p.ej., quitar o agregar un prefijo de ruta de acceso de una entrada de manifiesto si la configuración de hosting web no coincide con la configuración del sistema de archivos local. Como alternativa con más flexibilidad, puedes usar la opción
manifestTransforms
y proporcionar una función que modifique las entradas del manifiesto con la lógica que proporciones.Ejemplo de uso:
// Replace a '/dist/' prefix with '/', and also prepend // '/static' to every URL. modifyURLPrefix: { '/dist/': '/', '': '/static', }
-
cadena opcional
El valor predeterminado es null
Si se especifica, todas las solicitudes de navegación para las URL que no se hayan almacenado previamente en la caché se entregarán con el código HTML de la URL proporcionada. Debes pasar la URL de un documento HTML que se encuentre en el manifiesto de almacenamiento previo en caché. Este objeto se debe usar en una situación de app de una sola página, en la que deseas que todas las navegaciones usen un HTML de app Shell común.
-
RegExp[] opcional
Es un array opcional de expresiones regulares que restringe a qué URLs se aplica el comportamiento
navigateFallback
configurado. Esto resulta útil si solo se debe tratar un subconjunto de las URLs de tu sitio como parte de una app de una sola página. Si se configurannavigateFallbackDenylist
ynavigateFallbackAllowlist
, la lista de bloqueo tiene prioridad.Nota: Estas expresiones regulares se pueden evaluar en comparación con todas las URL de destino durante una navegación. Evita usar Expresiones regulares complejas. De lo contrario, los usuarios podrían experimentar demoras cuando navegan por el sitio.
-
RegExp[] opcional
Es un array opcional de expresiones regulares que restringe a qué URLs se aplica el comportamiento
navigateFallback
configurado. Esto resulta útil si solo un subconjunto de las URLs de tu sitio se debe tratar como parte de una app de una sola página. Si se configurannavigateFallbackDenylist
ynavigateFallbackAllowlist
, tiene prioridad la lista de bloqueo.Nota: Estas expresiones regulares se pueden evaluar en comparación con todas las URL de destino durante una navegación. Evita usar Expresiones regulares complejas. De lo contrario, los usuarios podrían experimentar demoras cuando navegan por el sitio.
-
booleano opcional
El valor predeterminado es false
Indica si se habilita o no la precarga de navegación en el service worker generado. Cuando se configura como verdadero, también debes usar
runtimeCaching
para configurar una estrategia de respuesta adecuada que coincida con las solicitudes de navegación y hacer uso de la respuesta precargada. -
offlineGoogleAnalytics
booleano | GoogleAnalyticsInitializeOptions opcional
El valor predeterminado es false
Controla si se incluye o no la compatibilidad con Google Analytics sin conexión. Cuando sea
true
, la llamada alinitialize()
deworkbox-google-analytics
se agregará al service worker generado. Cuando se establece en unObject
, ese objeto se pasará a la llamada ainitialize()
, lo que te permite personalizar el comportamiento. -
runtimeCaching
RuntimeCaching[] opcional
Cuando usas las herramientas de compilación de Workbox para generar tu service worker, puedes especificar una o más opciones de configuración de almacenamiento en caché en el entorno de ejecución. Luego, estas se traducen en llamadas
workbox-routing.registerRoute
con la configuración de coincidencias y controladores que definas.Para ver todas las opciones, consulta la documentación de
workbox-build.RuntimeCaching
. En el siguiente ejemplo, se muestra una configuración típica, con dos rutas de entorno de ejecución definidas: -
skipWaiting
booleano opcional
El valor predeterminado es false
Indica si se debe agregar una llamada incondicional a
skipWaiting()
al service worker generado. Si esfalse
, se agregará un objeto de escuchamessage
en su lugar, lo que permitirá que las páginas de los clientes activenskipWaiting()
llamando apostMessage({type: 'SKIP_WAITING'})
en un service worker en espera. -
mapa de fuentes
booleano opcional
El valor predeterminado es true
Indica si se debe crear un mapa de origen para los archivos de service worker generados.
-
swDest
cadena opcional
El valor predeterminado es: "service-worker.js"
El nombre del elemento del archivo del service worker creado por este complemento.
InjectManifest
Esta clase permite compilar un archivo de service worker proporcionado a través de swSrc
y, luego, insertar en él una lista de URL y de información de revisión para el almacenamiento previo en caché según la canalización de recursos del paquete web.
Usa una instancia de InjectManifest
en el array plugins
de una configuración de webhook.
Además de insertar el manifiesto, este complemento realizará una compilación del archivo swSrc
con las opciones de la configuración principal del paquete web.
// 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: '...',
});
Propiedades
-
constructor
void
Crea una instancia de InjectManifest.
La función
constructor
se ve de la siguiente manera:(config: WebpackInjectManifestOptions) => {...}
-
config
WebpackInjectManifestOptions
-
resultados
-
-
config
WebpackInjectManifestOptions
Propiedades
default
Tipo
objeto
Propiedades
-
GenerateSW
búsqueda
-
InjectManifest
búsqueda