workbox-build
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:
- Generate a complete service worker with precaching and some basic configurable options, writing the resulting service worker file to disk. See generateSW().
- Generate a complete service worker with precaching and some basic configurable options, without writing the results to disk. See generateSWString().
- 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().
- 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
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
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 toswDest
. Thesize
property contains the aggregate size of all the precached entries, in bytes, and thecount
property contains the total number of precached entries. Any non-fatal warning messages will be returned viawarnings
.
generateSWString
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. TheswString
property contains a string representation of the full service worker code. Any non-fatal warning messages will be returned viawarnings
.
getManifest
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. Thesize
property contains the aggregate size of all the precached entries, in bytes, thecount
property contains the total number of precached entries, and themanifestEntries
property contains all theManifestEntry
items. Any non-fatal warning messages will be returned viawarnings
.
injectManifest
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 toswDest
. Thesize
property contains the aggregate size of all the precached entries, in bytes, and thecount
property contains the total number of precached entries. Any non-fatal warning messages will be returned viawarnings
.
Abstract types
ManifestEntry
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
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
Object
Properties
Parameter |
|
---|---|
manifest |
Array of ManifestEntry |
warnings |
(Array of string or undefined) |