complemento-webpack-de-trabajo

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

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 de webpack. 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 de webpack.

  • 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 o dontCacheBustURLsMatching, 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 de webpack.

  • 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',
}
  • navigateFallback

    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.

  • navigateFallbackAllowlist

    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 configuran navigateFallbackDenylist y navigateFallbackAllowlist, 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.

  • navigateFallbackDenylist

    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 configuran navigateFallbackDenylist y navigateFallbackAllowlist, 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.

  • navigationPreload

    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 al initialize() de workbox-google-analytics se agregará al service worker generado. Cuando se establece en un Object, ese objeto se pasará a la llamada a initialize(), 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 es false, se agregará un objeto de escucha message en su lugar, lo que permitirá que las páginas de los clientes activen skipWaiting() llamando a postMessage({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

  • config

    WebpackInjectManifestOptions

Propiedades

default

Tipo

objeto

Propiedades

  • GenerateSW

    búsqueda

  • InjectManifest

    búsqueda