compilación-caja de trabajo

El módulo workbox-build se integra en un proceso de compilación basado en nodos y puede generar un service worker completo o solo una lista de recursos para almacenar en caché previamente que se podría usar dentro de un service worker existente.

Los dos modos que la mayoría de los desarrolladores usarán son generateSW y injectManifest. Las respuestas a las siguientes preguntas pueden ayudarte a elegir el modo y la configuración adecuados para usar.

Qué modo usar

generateSW

El modo generateSW crea un archivo de Service Worker para ti, personalizado a través de opciones de configuración, y lo escribe en el disco.

Cuándo usar generateSW

  • Quieres almacenar archivos en caché previamente.
  • Tienes necesidades simples de almacenamiento en caché en el tiempo de ejecución.

Cuándo NO se debe 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 las estrategias de almacenamiento en caché personalizadas.

injectManifest

El modo injectManifest generará una lista de URLs para almacenar en caché previamente y agregará ese manifiesto de caché previa a un archivo de Service Worker existente. De lo contrario, el archivo permanecerá tal como está.

Cuándo usar injectManifest

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

Cuándo NO se debe usar injectManifest

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

Modo generateSW

Puedes usar el modo generateSW dentro de una secuencia de comandos de compilación basada en nodos con las opciones de configuración más comunes, de la siguiente manera:

// Inside of build.js:
const {generateSW} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while generating a service worker:',
      warnings.join('\n')
    );
  }

  console.log(`Generated a service worker, which will precache ${count} files, totaling ${size} bytes.`);
});

Esto generará un Service Worker con la configuración de almacenamiento previo en caché para todos los archivos que se seleccionen en tu configuración y las reglas de almacenamiento en caché del tiempo de ejecución proporcionadas.

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

Modo injectManifest

Puedes usar el modo injectManifest dentro de una secuencia de comandos de compilación basada en nodos con las opciones de configuración más comunes, de la siguiente manera:

// Inside of build.js:
const {injectManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while injecting the manifest:',
      warnings.join('\n')
    );
  }

  console.log(`Injected a manifest which will precache ${count} files, totaling ${size} bytes.`);
});

Esto creará un manifiesto de almacenamiento previo en caché basado en los archivos que detecte tu configuración y lo insertará en tu archivo de Service Worker existente.

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

Modos adicionales

Esperamos que generateSW o injectManifest satisfagan las necesidades de la mayoría de los desarrolladores. Sin embargo, workbox-build admite otro modo que podría ser adecuado para ciertos casos de uso.

Modo getManifest

Conceptualmente, es similar al modo injectManifest, pero, en lugar de agregar el manifiesto al archivo del Service Worker fuente, devuelve el array de entradas del manifiesto, junto con información sobre la cantidad de entradas y el tamaño total.

Puedes usar el modo injectManifest dentro de una secuencia de comandos de compilación basada en nodos con las opciones de configuración más comunes, de la siguiente manera:

// Inside of build.js:
const {getManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
}).then(({manifestEntries, count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while getting the manifest:',
      warnings.join('\n')
    );
  }

  // Do something with the manifestEntries, and potentially log count and size.
});

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

Tipos

BasePartial

Propiedades

  • additionalManifestEntries

    (string | ManifestEntry)[] opcional

    Es una lista de entradas que se almacenarán previamente en la caché, además de las entradas que se generen como parte de la configuración de compilación.

  • dontCacheBustURLsMatching

    RegExp opcional

    Se supondrá que los recursos que coincidan con este patrón tienen versiones únicas a través de su URL y estarán exentos de la invalidación normal de la caché HTTP que se realiza cuando se completa la precaché. Si bien no es obligatorio, se recomienda que, si tu proceso de compilación existente ya inserta un valor de [hash] en cada nombre de archivo, proporciones una RegExp que lo detecte, ya que esto reducirá el ancho de banda consumido durante el almacenamiento previo en caché.

  • manifestTransforms

    ManifestTransform[] opcional

    Una o más funciones que se aplicarán de forma secuencial al manifiesto generado. Si también se especifican modifyURLPrefix o dontCacheBustURLsMatching, primero se aplicarán sus transformaciones correspondientes.

  • 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 se almacenen en caché previamente de forma involuntaria archivos muy grandes que podrían haber coincidido accidentalmente con uno de tus patrones.

  • modifyURLPrefix

    objeto opcional

    Es un objeto que asigna prefijos de cadenas a valores de cadenas de reemplazo. Esto se puede usar, p.ej., 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 más flexible, 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',
}

BuildResult

Tipo

Omit<GetManifestResult"manifestEntries"
> & object

Propiedades

  • filePaths

    string[]

GeneratePartial

Propiedades

  • babelPresetEnvTargets

    string[] opcional

    El valor predeterminado es: ["chrome >= 56"]

    Los objetivos para pasar a babel-preset-env cuando se transpila el paquete del service worker.

  • cacheId

    cadena opcional

    Es un ID opcional que se antepone a los nombres de la caché. Esto es muy útil para el desarrollo local, en el que varios sitios pueden publicarse desde el mismo origen http://localhost:port.

  • cleanupOutdatedCaches

    booleano opcional

    El valor predeterminado es false.

    Indica si Workbox debe intentar identificar y borrar los precachés creados por versiones anteriores incompatibles.

  • clientsClaim

    booleano opcional

    El valor predeterminado es false.

    Indica si el trabajador de servicio debe comenzar a controlar a los clientes existentes en cuanto se active.

  • directoryIndex

    cadena opcional

    Si una solicitud de navegación para una URL que termina en / no coincide con una URL almacenada previamente en caché, este valor se agregará a la URL y se verificará si hay una coincidencia de almacenamiento previo en caché. Este parámetro debe establecerse en lo que tu servidor web usa para su índice de directorio.

  • disableDevLogs

    booleano opcional

    El valor predeterminado es false.

  • ignoreURLParametersMatching

    RegExp[] opcional

    Se quitarán todos los nombres de parámetros de búsqueda que coincidan con una de las RegExp de este array antes de buscar una coincidencia en la caché previa. 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 de Service Worker generado. Esto es útil cuando quieres 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.

  • inlineWorkboxRuntime

    booleano opcional

    El valor predeterminado es false.

    Indica si el código de tiempo de ejecución de la biblioteca de Workbox debe incluirse en el service worker de nivel superior o dividirse en un archivo independiente que debe implementarse junto con el service worker. Mantener el tiempo 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.

  • Standard

    cadena opcional

    El valor predeterminado es "production".

    Si se configura como "production", se producirá un paquete de Service Worker optimizado que excluye la información de depuración. Si no se configura de forma explícita aquí, se usará el valor de process.env.NODE_ENV y, si no se puede, se recurrirá a 'production'.

  • navigateFallback

    cadena opcional

    El valor predeterminado es nulo.

    Si se especifica, todas las solicitudes de navegación para URLs que no se hayan almacenado previamente en caché se completarán con el código HTML de la URL proporcionada. Debes pasar la URL de un documento HTML que se encuentre en tu manifiesto de almacenamiento previo en caché. Esto se debe usar en un caso de aplicación de una sola página, en el que deseas que todas las navegaciones usen 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 de navigateFallback configurado. Esto es útil si solo un subconjunto de las URLs de tu sitio debe tratarse como parte de una aplicación 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 cada URL de destino durante una navegación. Evita usar expresiones regulares complejas, ya que tus usuarios podrían experimentar demoras cuando naveguen por tu sitio.

  • navigateFallbackDenylist

    RegExp[] opcional

    Es un array opcional de expresiones regulares que restringe a qué URLs se aplica el comportamiento de navigateFallback configurado. Esto es útil si solo un subconjunto de las URLs de tu sitio debe tratarse como parte de una aplicación 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 cada URL de destino durante una navegación. Evita usar expresiones regulares complejas, ya que tus usuarios podrían experimentar demoras cuando naveguen por tu sitio.

  • navigationPreload

    booleano opcional

    El valor predeterminado es false.

    Indica si se debe habilitar la precarga 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 utilizar la respuesta precargada.

  • offlineGoogleAnalytics

    boolean | GoogleAnalyticsInitializeOptions opcional

    El valor predeterminado es false.

    Controla si se incluye o no la compatibilidad con Google Analytics sin conexión. Cuando es true, la llamada al initialize() de workbox-google-analytics se agregará a tu service worker generado. Cuando se establece en un Object, ese objeto se pasará a la llamada de initialize(), lo que te permitirá 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 configuraciones de almacenamiento en caché en el tiempo de ejecución. Luego, se traducen a llamadas de 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 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 trabajador de servicio 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.

GenerateSWOptions

Tipo

BasePartial & GlobPartial & GeneratePartial & RequiredSWDestPartial & OptionalGlobDirectoryPartial

GetManifestOptions

Tipo

BasePartial y GlobPartial y RequiredGlobDirectoryPartial

GetManifestResult

Propiedades

  • count

    número

  • manifestEntries

    ManifestEntry[]

  • tamaño

    número

  • advertencias

    string[]

GlobPartial

Propiedades

  • globFollow

    booleano opcional

    El valor predeterminado es true.

    Determina si se siguen o no los vínculos simbólicos cuando se genera el manifiesto de almacenamiento previo en caché. Para obtener más información, consulta la definición de follow en la documentación de glob.

  • globIgnores

    string[] opcional

    El valor predeterminado es: ["**\/node_modules\/**\/*"]

    Es un conjunto de patrones que coinciden con los archivos que siempre se deben excluir cuando se genera el manifiesto de almacenamiento previo en caché. Para obtener más información, consulta la definición de ignore en la documentación de glob.

  • globPatterns

    string[] opcional

    El valor predeterminado es: ["**\/*.{js,wasm,css,html}"]

    Los archivos que coincidan con cualquiera de estos patrones se incluirán en el manifiesto de almacenamiento previo en caché. Para obtener más información, consulta la guía básica de glob.

  • templatedURLs

    objeto opcional

    Si una URL se renderiza en función de cierta lógica del servidor, su contenido puede depender de varios archivos o de algún otro valor de cadena único. Las claves de este objeto son URLs renderizadas por el servidor. Si los valores son un array de cadenas, se interpretarán como patrones de glob, y el contenido de los archivos que coincidan con los patrones se usará para versionar de forma única la URL. Si se usa con una sola cadena, se interpretará como información de versionado única que generaste para una URL determinada.

InjectManifestOptions

Tipo

BasePartial & GlobPartial & InjectPartial & RequiredSWDestPartial & RequiredGlobDirectoryPartial

InjectPartial

Propiedades

  • injectionPoint

    cadena opcional

    El valor predeterminado es: "self.__WB_MANIFEST"

    Es la cadena que se debe buscar dentro del archivo swSrc. Una vez que se encuentre, se reemplazará por el manifiesto de almacenamiento previo en caché generado.

  • swSrc

    string

    Ruta de acceso y nombre de archivo del archivo de Service Worker que se leerá durante el proceso de compilación, en relación con el directorio de trabajo actual.

ManifestEntry

Propiedades

  • integridad

    cadena opcional

  • revisión

    string

  • url

    string

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
): Promise<ManifestTransformResult> | ManifestTransformResult

Tipo

función

Parámetros

  • manifestEntries

    (ManifestEntry y object)[]

    • tamaño

      número

  • compilación

    desconocido opcional

Muestra

ManifestTransformResult

Propiedades

  • manifiesto

    (ManifestEntry y object)[]

    • tamaño

      número

  • advertencias

    string[] opcional

OptionalGlobDirectoryPartial

Propiedades

  • globDirectory

    cadena opcional

    Es el directorio local con el que deseas hacer coincidir globPatterns. La ruta de acceso es relativa al directorio actual.

RequiredGlobDirectoryPartial

Propiedades

  • globDirectory

    string

    Es el directorio local con el que deseas hacer coincidir globPatterns. La ruta de acceso es relativa al directorio actual.

RequiredSWDestPartial

Propiedades

  • swDest

    string

    Ruta de acceso y nombre de archivo del archivo de Service Worker que creará el proceso de compilación, en relación con el directorio de trabajo actual. Debe terminar en ".js".

RuntimeCaching

Propiedades

StrategyName

Enum

"CacheFirst"

"CacheOnly"

"NetworkFirst"

"NetworkOnly"

"StaleWhileRevalidate"

WebpackGenerateSWOptions

Tipo

BasePartial y WebpackPartial y GeneratePartial y WebpackGenerateSWPartial

WebpackGenerateSWPartial

Propiedades

  • importScriptsViaChunks

    string[] opcional

    Uno o más nombres de fragmentos de webpack. El contenido de esos fragmentos se incluirá en el trabajador de servicio generado a través de una llamada a importScripts().

  • swDest

    cadena opcional

    El valor predeterminado es "service-worker.js".

    Es el nombre del archivo de trabajador de servicio creado por este complemento.

WebpackInjectManifestOptions

Tipo

BasePartial y WebpackPartial y InjectPartial y WebpackInjectManifestPartial

WebpackInjectManifestPartial

Propiedades

  • compileSrc

    booleano opcional

    El valor predeterminado es true.

    Cuando se establece en true (el valor predeterminado), webpack compilará el archivo swSrc. Cuando false, no se realizará la compilación (y no se podrá usar webpackCompilationPlugins). Se establece en false si deseas insertar el manifiesto en, p.ej., un archivo JSON.

  • swDest

    cadena opcional

    Es el nombre del archivo de recursos del archivo de Service Worker que creará este complemento. Si se omite, el nombre se basará en el nombre de swSrc.

  • webpackCompilationPlugins

    any[] opcional

    Son complementos webpack opcionales que se usarán cuando se compile el archivo de entrada swSrc. Solo es válido si compileSrc es true.

WebpackPartial

Propiedades

  • fragmentos

    string[] opcional

    Uno o más nombres de fragmentos cuyos archivos de salida correspondientes se deben incluir en el manifiesto de la caché previa.

  • excluir

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

    Son uno o más especificadores que se usan para excluir activos del manifiesto de la caché previa. Esto se interpreta según las mismas reglas que la opción estándar exclude 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 la caché previa.

  • incluye

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

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

  • Standard

    cadena opcional

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

Métodos

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
): Promise<string>

Esto copia un conjunto de bibliotecas de tiempo de ejecución que usa Workbox en un directorio local, que se debe implementar junto con el archivo de tu service worker.

Como alternativa a la implementación de estas copias locales, puedes usar Workbox desde su URL de CDN oficial.

Este método se expone para beneficio de los desarrolladores que usan workbox-build.injectManifest y que prefieren no usar las copias de Workbox de la CDN. Los desarrolladores que usan workbox-build.generateSW no necesitan llamar a este método de forma explícita.

Parámetros

  • destDirectory

    string

    Es la ruta de acceso al directorio principal en el que se creará el nuevo directorio de bibliotecas.

Muestra

  • Promise<string>

    Es el nombre del directorio recién creado.

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
): Promise<BuildResult>

Este método crea una lista de URLs para almacenar en caché previamente, denominada "manifiesto de caché previa", según las opciones que proporciones.

También acepta opciones adicionales que configuran el comportamiento del service worker, como las reglas de runtimeCaching que debería usar.

Según el manifiesto de almacenamiento previo en caché y la configuración adicional, escribe un archivo de service worker listo para usar en el disco en swDest.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
});

Parámetros

Muestra

getManifest()

workbox-build.getManifest(
  config: GetManifestOptions,
): Promise<GetManifestResult>

Este método devuelve una lista de URLs para almacenar en caché previamente, denominada "manifiesto de caché previa", junto con detalles sobre la cantidad de entradas y su tamaño, según las opciones que proporciones.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, manifestEntries, size, warnings} = await getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
});

Parámetros

Muestra

getModuleURL()

workbox-build.getModuleURL(
  moduleName: string,
  buildType: BuildType,
): string

Parámetros

  • moduleName

    string

  • buildType

    BuildType

Muestra

  • string

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
): Promise<BuildResult>

Este método crea una lista de URLs para almacenar en caché previamente, denominada "manifiesto de caché previa", según las opciones que proporciones.

El manifiesto se inyecta en el archivo swSrc, y la cadena de marcador de posición injectionPoint determina en qué parte del archivo debe ir el manifiesto.

El archivo final del trabajador de servicio, con el manifiesto insertado, se escribe en el disco en swDest.

Este método no compilará ni agrupará tu archivo swSrc, solo se encargará de insertar el manifiesto.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
});

Parámetros

Muestra