complemento-webpack-de-trabajo

Workbox proporciona dos complementos de webpack: uno que genera un service worker completo y otro que genera una lista de recursos para almacenar previamente en caché que se inserta en un archivo de service worker.

Los complementos se implementan como dos clases en el módulo workbox-webpack-plugin, llamadas GenerateSW y InjectManifest. Las respuestas a las siguientes preguntas pueden ayudarte a elegir el complemento y la configuración correctos.

Qué complemento usar

GenerateSW

El complemento GenerateSW creará un archivo de service worker por ti y lo agregará a la canalización de recursos de webpack.

Cuándo usar GenerateSW

  • Quieres almacenar en caché los archivos de antemano.
  • Tienes necesidades de almacenamiento en caché del entorno de ejecución simples.

Cuándo NO usar GenerateSW

  • Quieres usar otras funciones de Service Worker (es decir, Web Push).
  • Quieres importar secuencias de comandos adicionales o agregar lógica adicional para estrategias de almacenamiento en caché personalizadas.

InjectManifest

El complemento InjectManifest generará una lista de URLs para almacenar previamente en caché y añadirá ese manifiesto de almacenamiento previo en caché a un archivo de service worker existente. De lo contrario, dejará el archivo tal como está.

Cuándo usar InjectManifest

  • Quieres tener más control sobre tu trabajador de servicio.
  • Quieres almacenar en caché previamente los archivos.
  • Debes personalizar el enrutamiento y las estrategias.
  • Quieres usar el service worker con otras funciones de la plataforma (p.ej., Web Push).

Cuándo NO usar InjectManifest

  • Quieres la ruta más fácil para agregar un service worker a tu sitio.

Generar complemento SW

Puedes agregar el complemento GenerateSW a tu configuración de 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 la configuración de almacenamiento en caché previo para todos los recursos de webpack que detecte 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 tu configuración de 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: '...',
    }),
  ],
};

Esto creará un manifiesto de almacenamiento en caché basado en los recursos de webpack que detectó tu configuración y lo insertará en tu archivo de service worker compilado y empaquetado.

Puedes encontrar un conjunto completo de opciones de configuración en la documentación de referencia.

Información adicional

Puedes encontrar orientación para usar 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 nuevo archivo de service worker listo para usar como parte del proceso de compilación del paquete web.

Usa una instancia de GenerateSW en el array plugins de una configuración de webpack.

// 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

    (cadena | ManifestEntry)[] opcional

    Es una lista de entradas que se almacenarán en caché previamente, además de las entradas que se generan 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 transpile el paquete del trabajador de servicio.

  • cacheId

    string opcional

    Un ID opcional que se antepondrá 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 de http://localhost:port.

  • trozos

    string[] opcional

    Uno o más nombres de fragmentos cuyos archivos de salida correspondientes deben incluirse en el manifiesto de almacenamiento previo en caché.

  • cleanupOutdatedCaches

    booleano opcional

    El valor predeterminado es false.

    Define si Workbox debe intentar identificar y borrar las precachés creadas por versiones anteriores incompatibles.

  • clientsClaim

    booleano opcional

    El valor predeterminado es false.

    Indica si el service worker debe comenzar a controlar cualquier cliente existente en cuanto se active.

  • directoryIndex

    cadena opcional

    Si una solicitud de navegación de una URL que termina en / no coincide con una URL almacenada en caché previamente, este valor se agregará a la URL y se verificará si corresponde a una coincidencia en caché previamente. Se debe configurar según lo que usa tu servidor web para su índice de directorio.

  • disableDevLogs

    booleano opcional

    El valor predeterminado es false.

  • dontCacheBustURLsMatching

    RegExp opcional

    Se supondrá que los recursos que coincidan con esto tienen una versión única a través de su URL y están exentos de la eliminación normal de la caché HTTP que se realiza cuando se completa la caché previa. Si bien no es obligatorio, se recomienda que, si tu proceso de compilación existente ya inserta un valor [hash] en cada nombre de archivo, proporciones una RegExp que lo detecte, ya que reducirá el ancho de banda que se consume durante la precarga.

  • excluir

    (cadena | RegExp | función)[] opcional

    Uno o más especificadores que se usan para excluir activos del manifiesto de almacenamiento en caché previo. Esto se interpreta según 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 fragmentos cuyos archivos de salida correspondientes se deben excluir del manifiesto de almacenamiento en caché.

  • ignoreURLParametersMatching

    RegExp[] opcional

    Se quitarán todos los nombres de parámetros de búsqueda que coincidan con uno de los RegExp de este array antes de buscar una coincidencia de almacenamiento en caché previo. Esto es útil si tus usuarios pueden solicitar URLs que contengan, por ejemplo, parámetros de URL que se usan para hacer un seguimiento de la fuente del tráfico. Si no se proporciona, el valor predeterminado es [/^utm_/, /^fbclid$/].

  • importScripts

    string[] opcional

    Es una lista de archivos JavaScript que se deben pasar a importScripts() dentro del archivo del service worker generado. Esto es útil cuando deseas permitir que Workbox cree tu archivo de service worker de nivel superior, pero deseas incluir algún 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 a través de una llamada a importScripts().

  • incluye

    (cadena | RegExp | función)[] opcional

    Uno o más especificadores que se usan para incluir recursos en el manifiesto de almacenamiento en caché previo. Esto se interpreta según las mismas reglas que la opción include estándar de webpack.

  • inlineWorkboxRuntime

    booleano opcional

    El valor predeterminado es false.

    Indica 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 debe implementarse 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 tu 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 la caché previamente. Esto evita que almacenes en caché de forma previa, por error, archivos muy grandes que podrían haber coincidido accidentalmente con uno de tus patrones.

  • Standard

    cadena opcional

    Si se establece en "producción", se producirá un paquete de trabajador de servicio optimizado que excluye la información de depuración. Si no se configura de forma explícita aquí, se usará el valor mode configurado en la compilación webpack actual.

  • modifyURLPrefix

    objeto opcional

    Un objeto de asignación de prefijos de string para reemplazar valores de string. Esto se puede usar, por ejemplo, para quitar o agregar un prefijo de ruta de acceso de una entrada de manifiesto si la configuración de tu hosting web no coincide con la configuración de tu 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 cualquier 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 URLs que no se almacenaron en caché previamente se completarán con el HTML de la URL proporcionada. Debes pasar la URL de un documento HTML que aparezca en el manifiesto de almacenamiento previo en caché. Se diseñó para usarse en una app de una sola página, en la que deseas que todas las navegaciones usen un código HTML de Shell de la app común.

  • navigateFallbackAllowlist

    RegExp[] opcional

    Es un array opcional de expresiones regulares que restringe a qué URLs se aplica el comportamiento navigateFallback configurado. Esto es útil si solo un subconjunto de las URLs de tu sitio debe considerarse parte de una app de una sola página. Si se configuran navigateFallbackDenylist y navigateFallbackAllowlist, la lista de entidades rechazadas tiene prioridad.

    Nota: Estas RegExps se pueden evaluar en función de cada URL de destino durante una navegación. Evita usar RegExps complejas, de lo contrario, es posible que los usuarios vean demoras cuando naveguen por tu sitio.

  • navigateFallbackDenylist

    RegExp[] opcional

    Es un array opcional de expresiones regulares que restringe las URLs a las que se aplica el comportamiento de navigateFallback configurado. Esto es útil si solo un subconjunto de las URLs de tu sitio debe considerarse parte de una app de una sola página. Si se configuran navigateFallbackDenylist y navigateFallbackAllowlist, la lista de entidades rechazadas tiene prioridad.

    Nota: Estos RegExps pueden evaluarse en comparación con cada URL de destino durante una navegación. Evita usar RegExps complejos. De lo contrario, es posible que los usuarios experimenten demoras cuando naveguen por tu sitio.

  • navigationPreload

    booleano opcional

    El valor predeterminado es false.

    Indica si se debe habilitar o no la carga previa de navegación en el service worker generado. Cuando se establece como verdadero, también debes usar runtimeCaching para configurar una estrategia de respuesta adecuada que coincida con las solicitudes de navegación y usar la respuesta precargada.

  • offlineGoogleAnalytics

    booleano | GoogleAnalyticsInitializeOptions opcional

    El valor predeterminado es false.

    Controla si se debe incluir o no la compatibilidad con Google Analytics sin conexión. Cuando sea true, la llamada a initialize() de workbox-google-analytics se agregará a tu trabajador de servicio generado. Cuando se establece en Object, ese objeto se pasa a la llamada initialize(), lo que te permite personalizar el comportamiento.

  • runtimeCaching

    RuntimeCaching[] opcional

    Cuando usas las herramientas de compilación de Workbox para generar tu trabajador del servicio, puedes especificar uno o más parámetros de configuración de almacenamiento en caché del entorno de ejecución. Luego, se traducen a llamadas workbox-routing.registerRoute con la configuración de coincidencia y controlador 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 trabajador de servicio generado. Si es false, se agregará un objeto de escucha message, lo que permitirá que las páginas del cliente activen skipWaiting() llamando a postMessage({type: 'SKIP_WAITING'}) en un service worker en espera.

  • sourcemap

    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"

    Es el nombre del activo del archivo del servicio trabajador que crea este complemento.

InjectManifest

Esta clase admite la compilación de un archivo de trabajador de servicio proporcionado a través de swSrc y la inserción en ese trabajador de servicio de una lista de URLs y de información de revisión para el almacenamiento en caché previo según la canalización de recursos de Webpack.

Usa una instancia de InjectManifest en el array plugins de una configuración de webpack.

Además de insertar el manifiesto, este complemento realizará una compilación del archivo swSrc con las opciones de la configuración principal de Webpack.

// 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

Propiedades

default

Tipo

objeto

Propiedades

  • GenerateSW

    consulta

  • InjectManifest

    consulta