workbox-build
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.
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, filePaths: Array of string, 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 The configuration to use. Values in
|
- Returns
-
Promise containing {count: number, filePaths: Array of string, size: number, warnings: Array of string}
A promise that resolves once the service worker and related files (indicated byfilePaths
) 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
.
getManifest
getManifest(config) returns Promise containing {count: number, manifestEntries: Array of module:workbox-build.ManifestEntry, 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 The configuration to use. Values in
|
- Returns
-
Promise containing {count: number, manifestEntries: Array of module:workbox-build.ManifestEntry, size: number, warnings: Array of string}
A promise that resolves once the precache manifest (available in themanifestEntries
property) has been determined. 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
.
injectManifest
injectManifest(config) returns Promise containing {count: number, filePaths: Array of string, 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 placeholder string
injectionPoint
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 The configuration to use. Values in
|
- Returns
-
Promise containing {count: number, filePaths: Array of string, size: number, warnings: Array of string}
A promise that resolves once the service worker and related files (indicated byfilePaths
) 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 |
Optional string The revision details for the file. This is a hash generated by node based on the file contents. |
integrity |
Optional string Integrity metadata that will be used when making the network request for the URL. |
ManifestTransform
ManifestTransform(manifestEntries, compilation) returns Promise containing 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. |
compilation |
Optional Object When used in the webpack plugins, this param
will be set to the current |
- Returns
-
Promise containing 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
A transformation that prepended the origin of a CDN for any
URL starting with '/assets/' could be implemented as:
const cdnTransform = async (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: []};
};
A transformation that nulls the revision field when the
URL contains an 8-character hash surrounded by '.', indicating that it
already contains revision information:
const removeRevisionTransform = async (manifestEntries) => {
const manifest = manifestEntries.map(entry => {
const hashRegExp = /\.\w{8}\./;
if (entry.url.match(hashRegExp)) {
entry.revision = null;
}
return entry;
});
return {manifest, warnings: []};
};
ManifestTransformResult
Object
Properties
Parameter |
|
---|---|
manifest |
Array of module:workbox-build.ManifestEntry |
warnings |
(Array of string or undefined) |
RuntimeCachingEntry
Object
Properties
Parameter |
|||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
handler |
(string or module:workbox-routing~handlerCallback) Either the name of one of the built-in strategy classes, or custom handler callback to use when the generated route matches. |
||||||||||||||||||||||||||||||||||||||||
urlPattern |
(string, RegExp, or module:workbox-routing~matchCallback) The value that will be passed to |
||||||||||||||||||||||||||||||||||||||||
method |
Optional string The HTTP method that will match the generated route. |
||||||||||||||||||||||||||||||||||||||||
options |
Optional Object Values in
|