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 Object

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 ManifestEntry

The full array of entries, prior to the current transformation.

Returns

{manifest: Array of ManifestEntry, warnings: (Array of String or undefined)} 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: []};
};