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 trabajador de servicio completo o solo una lista de recursos para la caché previa que se podría usar en un trabajador de servicio existente.

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

Qué modo usar

generateSW

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

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 modo injectManifest generará una lista de URLs para almacenar previamente en caché y agregará 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é los archivos de antemano.
  • Debes personalizar el enrutamiento y las estrategias.
  • Quieres usar tu trabajador de servicio 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.

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 en caché previo para todos los archivos 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.

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 en caché previo basado en los archivos que detectó tu configuración y lo insertará en tu archivo de trabajador de servicio existente.

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

Modos adicionales

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

Modo getManifest

Esto es conceptualmente similar al modo injectManifest, pero en lugar de agregar el manifiesto al archivo del trabajador del servicio 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 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

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

  • dontCacheBustURLsMatching

    RegExp opcional

    Se considerará que los recursos que coincidan con esta opción tienen una versión única a través de su URL y están exentos de la eliminación de la caché HTTP normal 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.

  • 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, 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 almacenes en caché de forma previa, por error, archivos muy grandes que podrían haber coincidido accidentalmente con uno de tus patrones.

  • modifyURLPrefix

    objeto opcional

    Un objeto que asigna prefijos de cadenas a valores de cadenas de reemplazo. 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',
}

BuildResult

Tipo

Omite<GetManifestResult"manifestEntries"
> & 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 transpile el paquete del trabajador de servicio.

  • cacheId

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

  • cleanupOutdatedCaches

    booleano opcional

    El valor predeterminado es false.

    Indica si Workbox debe intentar identificar y borrar los almacenamientos en caché previos que crearon 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 para una URL que termina en / no coincide con una URL almacenada en caché, este valor se agregará a la URL y se verificará si hay una coincidencia de almacenamiento en caché. Debe establecerse en lo que usa tu servidor web 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 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 código adicional, como un objeto de escucha de eventos push.

  • inlineWorkboxRuntime

    booleano opcional

    El valor predeterminado es false.

    Si el código de tiempo de ejecución de la biblioteca de Workbox se debe incluir en el trabajador de servicio de nivel superior o dividir en un archivo independiente que se debe implementar junto con el trabajador de servicio. 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.

  • Standard

    cadena opcional

    El valor predeterminado es: "production"

    Si se establece en "production", se producirá un paquete de trabajador de servicio optimizado que excluirá la información de depuración. Si no se configura de forma explícita aquí, se usará el valor process.env.NODE_ENV y, de lo contrario, se usará 'production'.

  • 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 tu manifiesto de almacenamiento en caché previo. 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 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.

  • 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 incluye 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 un Object, ese objeto se pasará a la llamada initialize(), lo que te permitirá 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 tiempo 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.

GenerateSWOptions

Tipo

BasePartial & GlobPartial & GeneratePartial & RequiredSWDestPartial & OptionalGlobDirectoryPartial

GetManifestOptions

Tipo

BasePartial & GlobPartial & 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 los symlinks cuando se genera el manifiesto de almacenamiento en caché previo. 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 en caché previo. 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 en caché previo. Para obtener más información, consulta el instructivo de glob.

  • globStrict

    booleano opcional

    El valor predeterminado es true.

    Si es verdadero, un error de lectura de un directorio cuando se genera un manifiesto de almacenamiento en caché previo hará que la compilación falle. 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 renderiza en función de 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 renderizadas por el servidor. Si los valores son un array de cadenas, se interpretarán como patrones glob, y el contenido de cualquier archivo que coincida con los patrones se usará para crear una versión única de la URL. Si se usa con una sola cadena, se interpretará como información de control de versiones ú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 encontrar dentro del archivo swSrc. Una vez que se encuentre, se reemplazará por el manifiesto de almacenamiento en caché generado.

  • swSrc

    string

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

Tipo

función

Parámetros

  • manifestEntries

    (ManifestEntry & object)[]

    • tamaño

      número

  • compilación

    desconocido opcional

Muestra

ManifestTransformResult

Propiedades

  • manifiesto

    (ManifestEntry & 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 se relaciona con el directorio actual.

RequiredGlobDirectoryPartial

Propiedades

  • globDirectory

    string

    Es el directorio local con el que deseas hacer coincidir globPatterns. La ruta de acceso se relaciona con el directorio actual.

RequiredSWDestPartial

Propiedades

  • swDest

    string

    La ruta de acceso y el nombre del archivo del trabajador de servicio 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 & WebpackPartial & GeneratePartial & 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 a través de una llamada a importScripts().

  • swDest

    cadena opcional

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

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

WebpackInjectManifestOptions

Tipo

BasePartial & WebpackPartial & InjectPartial & WebpackInjectManifestPartial

WebpackInjectManifestPartial

Propiedades

  • compileSrc

    booleano opcional

    El valor predeterminado es true.

    Cuando sea true (la opción predeterminada), webpack compilará el archivo swSrc. Cuando sea false, no se realizará la compilación (y no se puede usar webpackCompilationPlugins). Establece en false si deseas insertar el manifiesto en, por ejemplo, un archivo JSON.

  • swDest

    cadena opcional

    Es el nombre del activo del archivo del trabajador de servicio que creará este plugin. Si se omite, el nombre se basará en el nombre 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 almacenamiento en caché previo.

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

  • incluye

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

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

  • 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 de mode configurado en la compilación webpack actual.

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 se debe implementar junto con tu archivo de trabajador de servicio.

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

Este método se expone para beneficiar a 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 superior 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,
)

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

También toma opciones adicionales que configuran el comportamiento del trabajador de servicio, como cualquier regla runtimeCaching que deba usar.

En función del manifiesto de almacenamiento en caché previo y la configuración adicional, escribe un archivo de servicio de trabajador 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,
)

Este método muestra una lista de URLs para almacenar en caché previamente, denominada "manifiesto de almacenamiento en caché previamente", 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,
)

Parámetros

  • moduleName

    string

  • buildType

    BuildType

Muestra

  • string

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
)

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

El manifiesto se inserta en el archivo swSrc, y la cadena de marcador de posición injectionPoint determina dónde debe ir el manifiesto en el archivo.

El archivo de servicio en primer plano final, 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