Module: workbox-build

workbox-build

module

Version     v3.1.0

This Node module can be used to generate a list of assets that should be precached in a service worker, generating a hash that can be used to intelligently update a cache when the service worker is updated.

This module will use glob patterns to find assets in a given directory and use the resulting URL and revision data for one of the follow uses:

1. Generate a complete service worker with precaching and some basic configurable options, writing the resulting service worker file to disk. See generateSW().
2. Generate a complete service worker with precaching and some basic configurable options, without writing the results to disk. See generateSWString().
3. Inject a manifest into an existing service worker. This allows you to control your own service worker while still taking advantage of workboxSW.precache() logic. See injectManifest().
4. Just generate a manifest, not a full service worker file. This is useful if you want to make use of the manifest from your own existing service worker file and are okay with including the manifest yourself. See getManifest().

Methods

copyWorkboxLibraries

static

copyWorkboxLibraries(destDirectory) returns Promise containing string

This copies over a set of runtime libraries used by Workbox into a local directory, which should be deployed alongside your service worker file.

As an alternative to deploying these local copies, you could instead use Workbox from its official CDN URL.

This method is exposed for the benefit of developers using injectManifest() who would prefer not to use the CDN copies of Workbox. Developers using generateSW() don't need to explicitly call this method, as it's called automatically when importWorkboxFrom is set to local.

Parameter
destDirectory	string The path to the parent directory under which the new directory of libraries will be created.

Returns

Promise containing string The name of the newly created directory.

generateSW

async   static

generateSW(config) returns Promise containing {count: Number, size: Number, warnings: Array of String}

This method creates a list of URLs to precache, referred to as a "precache manifest", based on the options you provide.

It also takes in additional options that configures the service worker's behavior, like any runtimeCaching rules it should use.

Based on the precache manifest and the additional configuration, it writes a ready-to-use service worker file to disk at swDest.

Parameter
config	Object Please refer to the configuration guide.

Returns

Promise containing {count: Number, size: Number, warnings: Array of String} A promise that resolves once the service worker file has been written to swDest. The size property contains the aggregate size of all the precached entries, in bytes, and the count property contains the total number of precached entries. Any non-fatal warning messages will be returned via warnings.

generateSWString

async   static

generateSWString(config) returns Promise containing {swString: String, warnings: Array of String}

This method generates a service worker based on the configuration options provided.

Parameter
config	Object Please refer to the configuration guide.

Returns

Promise containing {swString: String, warnings: Array of String} A promise that resolves once the service worker template is populated. The swString property contains a string representation of the full service worker code. Any non-fatal warning messages will be returned via warnings.

getManifest

async   static

getManifest(config) returns Promise containing {manifestEntries: Array of ManifestEntry, count: Number, size: Number, warnings: Array of String}

This method returns a list of URLs to precache, referred to as a "precache manifest", along with details about the number of entries and their size, based on the options you provide.

Parameter
config	Object Please refer to the configuration guide.

Returns

Promise containing {manifestEntries: Array of ManifestEntry, count: Number, size: Number, warnings: Array of String} A promise that resolves once the precache manifest is determined. The size property contains the aggregate size of all the precached entries, in bytes, the count property contains the total number of precached entries, and the manifestEntries property contains all the ManifestEntry items. Any non-fatal warning messages will be returned via warnings.

injectManifest

async   static

injectManifest(config) returns Promise containing {count: Number, size: Number, warnings: Array of String}

This method creates a list of URLs to precache, referred to as a "precache manifest", based on the options you provide.

The manifest is injected into the swSrc file, and the regular expression injectionPointRegexp determines where in the file the manifest should go.

The final service worker file, with the manifest injected, is written to disk at swDest.

Parameter
config	Object Please refer to the configuration guide.

Returns

Promise containing {count: Number, size: Number, warnings: Array of String} A promise that resolves once the service worker file has been written to swDest. The size property contains the aggregate size of all the precached entries, in bytes, and the count property contains the total number of precached entries. Any non-fatal warning messages will be returned via warnings.

Abstract types

ManifestEntry

static

Object

Properties

Parameter
url	String The URL to the asset in the manifest.
revision	String The revision details for the file. This is a hash generated by node based on the file contents.

ManifestTransform

static

ManifestTransform(manifestEntries) returns module:workbox-build.ManifestTransformResult

A ManifestTransform function can be used to modify the modify the url or revision properties of some or all of the ManifestEntries in the manifest.

Deleting the revision property of an entry will cause the corresponding url to be precached without cache-busting parameters applied, which is to say, it implies that the URL itself contains proper versioning info. If the revision property is present, it must be set to a string.

Parameter
manifestEntries	Array of module:workbox-build.ManifestEntry The full array of entries, prior to the current transformation.

Returns

module:workbox-build.ManifestTransformResult The array of entries with the transformation applied, and optionally, any warnings that should be reported back to the build tool.

Examples

<caption>A transformation that prepended the origin of a CDN for any
URL starting with '/assets/' could be implemented as:</caption>

const cdnTransform = (manifestEntries) => {
  const manifest = manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
  return {manifest, warnings: []};
};

<caption>A transformation that removes the revision field when the
URL contains an 8-character hash surrounded by '.', indicating that it
already contains revision information:</caption>

const removeRevisionTransform = (manifestEntries) => {
  const manifest = manifestEntries.map(entry => {
    const hashRegExp = /\.\w{8}\./;
    if (entry.url.match(hashRegExp)) {
      delete entry.revision;
    }
    return entry;
  });
  return {manifest, warnings: []};
};

ManifestTransformResult

static

Object

Properties

Parameter
manifest	Array of ManifestEntry
warnings	(Array of string or undefined)