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 simplemente una lista de elementos para almacenar previamente en caché que podrían usarse en 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 correctos para usar.

Qué modo usar

generateSW

El modo generateSW crea un archivo de service worker, personalizado mediante las opciones de configuración, y lo escribe en el disco.

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 modo injectManifest generará una lista de URLs para almacenar en caché y agregará ese manifiesto de precaché 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.

Modo generateSW

Puedes usar el modo generateSW dentro de una secuencia de comandos de compilación basada en nodos, mediante 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 configuración de almacenamiento previo en caché para todos los archivos 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.

Modo injectManifest

Puedes usar el modo injectManifest dentro de una secuencia de comandos de compilación basada en nodos, mediante 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 precaché basado en los archivos recogidos por 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.

Medios adicionales

Esperamos que generateSW o injectManifest se adapten a las necesidades de la mayoría de los desarrolladores. Sin embargo, workbox-build tiene otro modo compatible con el que podría ser apropiado para ciertos casos de uso.

Modo getManifest

Conceptualmente, es similar al modo injectManifest, pero, en lugar de agregar el manifiesto al archivo de service worker de origen, muestra 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, mediante 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

    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.

  • 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.

  • 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.

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

BuildResult

Tipo

Omite<GetManifestResult"manifestEntries"
> y el objeto

Propiedades

  • filePaths

    string[]

GeneratePartial

Propiedades

  • 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.

  • 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

  • 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.

  • 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.

  • Standard

    cadena opcional

    El valor predeterminado es: "production"

    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 process.env.NODE_ENV y, si no se configura, recurre a 'production'.

  • 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.

GenerateSWOptions

Tipo

BasePartial y GlobPartial y GeneratePartial y RequiredSWDestPartial y OptionalGlobDirectoryPartial

GetManifestOptions

Tipo

BasePartial y GlobPartial y RequiredGlobDirectoryPartial

GetManifestResult

Propiedades

  • recuento

    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 symlinks cuando se genera el manifiesto de precaché. 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\/**\/*"]

    Un conjunto de patrones que coinciden con archivos que siempre se excluirán cuando se genere el manifiesto de precaché. 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 alguno de estos patrones se incluirán en el manifiesto de precaché. Para obtener más información, consulta el manual de glob.

  • globStrict

    booleano opcional

    El valor predeterminado es true

    Si es verdadero, un error que lee un directorio cuando se genera un manifiesto de precaché hará que falle la compilación. Si es falso, se omitirá el directorio problemático. Para obtener más información, consulta la definición de strict en la documentación de glob.

  • templatedURLs

    objeto opcional

    Si una URL se procesa según alguna 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 que procesa el servidor. Si los valores son un array de cadenas, se interpretarán como patrones glob, y el contenido de los archivos que coincidan con los patrones se usará para crear una versión única de la URL. Si se usa con una sola string, se interpretará como información de control de versiones única que generaste para una URL determinada.

InjectManifestOptions

Tipo

BasePartial y GlobPartial y InjectPartial y RequiredSWDestPartial y RequiredGlobDirectoryPartial

InjectPartial

Propiedades

  • injectionPoint

    cadena opcional

    El valor predeterminado es "self.__WB_MANIFEST"

    Es la cadena que se debe encontrar dentro del archivo swSrc. Una vez que se encuentre, se reemplazará por el manifiesto de precaché generado.

  • swSrc

    cadena

    La ruta de acceso y el nombre de archivo del archivo del 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

    cadena

  • url

    cadena

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
)

Tipo

la función

Parámetros

  • manifestEntries

    (ManifestEntry y objeto)[]

    • tamaño

      número

  • compilación

    desconocido opcional

Devuelve

ManifestTransformResult

Propiedades

  • manifiesto

    (ManifestEntry y objeto)[]

    • tamaño

      número

  • advertencias

    string[] opcional

OptionalGlobDirectoryPartial

Propiedades

  • globDirectory

    cadena opcional

    El directorio local con el que deseas establecer coincidencias para globPatterns. La ruta es relativa al directorio actual.

RequiredGlobDirectoryPartial

Propiedades

  • globDirectory

    cadena

    El directorio local con el que deseas establecer coincidencias para globPatterns. La ruta es relativa al directorio actual.

RequiredSWDestPartial

Propiedades

  • swDest

    cadena

    La ruta de acceso y el nombre de archivo del archivo del service worker que se creará durante el proceso de compilación, en relación con el directorio de trabajo actual. Debe terminar en ".js".

RuntimeCaching

Propiedades

StrategyName

Enum

"CacheFirst"

"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 service worker generado mediante una llamada a importScripts().

  • swDest

    cadena opcional

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

    El nombre del elemento del archivo del service worker creado por este complemento.

WebpackInjectManifestOptions

Tipo

BasePartial y WebpackPartial y InjectPartial y WebpackInjectManifestPartial

WebpackInjectManifestPartial

Propiedades

  • compileSrc

    booleano opcional

    El valor predeterminado es true

    Cuando true (la opción predeterminada), webpack compilará el archivo swSrc. Cuando sea false, no se realizará la compilación (y no se podrá usar webpackCompilationPlugins). Configúralo como false si deseas inyectar el manifiesto, p.ej., en un archivo JSON.

  • swDest

    cadena opcional

    El nombre del elemento del archivo del service worker que creará este complemento. Si se omite, el nombre se basará en el nombre swSrc.

  • webpackCompilationPlugins

    any[] opcional

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

WebpackPartial

Propiedades

  • fragmentos

    string[] opcional

    Uno o más nombres de fragmento cuyos archivos de salida correspondientes se deben incluir en el manifiesto de precaché.

  • 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é.

  • 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.

  • 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.

Métodos

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
)

Esto copia un conjunto de bibliotecas del entorno de ejecución que usa Workbox en un directorio local, que debe implementarse junto con el archivo del service worker.

Como alternativa a implementar estas copias locales, puedes usar Workbox desde la URL de CDN oficial.

Este método se expone en beneficio de los desarrolladores que usan workbox-build.injectManifest, quienes preferirían no usar las copias de CDN de Workbox. Los desarrolladores que usan workbox-build.generateSW no necesitan llamar a este método de forma explícita.

Parámetros

  • destDirectory

    cadena

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

Devuelve

  • Promesa<string>

    El nombre del directorio recién creado.

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
)

Este método crea una lista de URLs que se almacenan previamente en caché, denominada "manifiesto de almacenamiento previo en caché", según las opciones que proporciones.

También incluye opciones adicionales que configuran el comportamiento del service worker, como cualquier regla runtimeCaching que debería usar.

Según el manifiesto de precaché 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

Devuelve

getManifest()

workbox-build.getManifest(
  config: GetManifestOptions,
)

Este método muestra una lista de URLs que se almacenan en caché, lo que se conoce como “manifiesto de almacenamiento previo en caché”, 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

Devuelve

getModuleURL()

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

Parámetros

  • moduleName

    cadena

  • buildType

    BuildType

Devuelve

  • cadena

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
)

Este método crea una lista de URLs que se almacenan previamente en caché, denominada "manifiesto de almacenamiento previo en caché", según las opciones que proporciones.

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

El archivo de service worker final, con el manifiesto insertado, se escribe en el disco, en swDest.

Este método no compilará ni empaquetará tu archivo swSrc; solo controla la inserción del 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

Devuelve