Workbox webpack Plugins

Workbox provides two webpack plugins: one that generates a complete service worker for you and one that generates a list of assets to precache that is injected into a service worker file.

The plugins are implemented as two classes in the workbox-webpack-plugin module, named GenerateSW and InjectManifest. The answers to the following questions can help you choose the right plugin and configuration to use.

Which Plugin to Use

GenerateSW Plugin

The GenerateSW plugin will create a service worker file for you and add it to the webpack asset pipeline.

When to use generateSW

  • You want to precache files.
  • You have simple runtime configuration needs (e.g. the configuration allows you to define routes and strategies).

When NOT to use generateSW

  • You want to use other Service Worker features (i.e. Web Push).
  • You want to import additional scripts or add additional logic.

InjectManifest Plugin

The InjectManifest plugin will generate a list of URLs to precache and add that precache manifest to an existing service worker file. It will otherwise leave the file as-is.

When to use injectManifest

  • You want more control over your service worker.
  • You want to precache files.
  • You have more complex needs in terms of routing.
  • You would like to use your service worker with other API's (e.g. Web Push).

When NOT to use injectManifest

  • You want the easiest path to adding a service worker to your site.

GenerateSW Plugin

You can add the GenerateSW plugin to your webpack config like so:

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW()
  ]
};

This will generate a service worker with precaching setup for all of your webpack assets.

Full GenerateSW Config

If you want to use any of the configuration options for the GenerateSW plugin, you'd just need to add an Object to the plugin's constructor.

For example:

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      option: 'value',
    })
  ]
};
These options apply to the webpack compilation.

swDest

Optional String, defaulting to `'service-worker.js'`

The path and filename of the service worker file that will be created by the build process, relative to the webpack output directory.

Example:

swDest: 'custom-sw-name.js'

importWorkboxFrom

Optional String, defaulting to 'cdn'

Valid values are 'cdn', 'local', and 'disabled.

  • 'cdn', the default, will use a URL for the Workbox runtime libraries hosted on a highly-available Google Cloud Storage instance.
  • 'local' will copy all of the Workbox runtime libraries into a versioned directory alongside your generated service worker, and configure the service worker to use those local copies. This option is provided for developers who would prefer to host everything themselves and not rely on the Google Cloud Storage CDN.
  • 'disabled' will opt-out automatic behavior. It's up to you to host a local copy of the Workbox libraries at your preferred URL, and to pass in the correct path to workbox-sw.js via the importScripts configuration option.
  • Note: In webpack, passing in a string corresponding to the webpack chunk name containing a custom Workbox runtime library bundle is also supported.

Example:

importWorkboxFrom: 'local'

chunks

Optional Array of String, defaulting to []

By default, Workbox will precache assets regardless of which chunk the asset is part of.

If you would like to override this behavior via a whitelist, specify one or more chunk names. Only assets belonging to those chunks will be precached; any assets belonging to another chunk or without a chunk association will be skipped.

Example:

// *Only* include assets that belong to these chunks:
chunks: ['chunk-name-1', 'chunk-name-2']

excludeChunks

Optional Array of String, defaulting to []

By default, Workbox will precache all assets generated by the webpack compilation, regardless of which chunk the asset is part of.

If you would like to override this behavior via a blacklist, specify one or more chunk names. Any assets belonging to those chunks will be skipped.

Example:

// Exclude assets that belong to these chunks:
excludeChunks: ['chunk-name-1', 'chunk-name-2']

include

Optional Array of RegExp or String

This allows you to only include assets matching any of the provided criteria when creating the precache manifest. It provides a filename-based approach to filtering.

This filtering takes place after any chunk-based filtering is applied.

In keeping with webpack convention, the option `test` can be used as an alias/alternative to `include`.

Example:

// Only include HTML and JS assets when precaching:
include: [/\.html$/, /\.js$/]

exclude

Optional Array of RegExp or String, defaulting to [/\.map$/, /^manifest.*\.js(?:on)?$/]

This allows you to specifically omit assets matching any of the provided criteria from being included in the precache manifest. It provides a filename-based approach to filtering.

This filtering takes place after any chunk-based filtering is applied.

Example:

// Exclude JPG and PNG assets from precaching:
exclude: [/\.jpg$/, /\.png$/]

importsDirectory

Optional String, defaulting to ''

Workbox creates assets as part of your webpack build process: a precache manifest file, and potentially a local copy of the Workbox libraries (if importWorkboxFrom is set to 'local').

These assets will, by default, be created at the root of your webpack build directory, i.e. output.path. You can set the importsDirectory option if you want these assets to be created in a subdirectory of output.path instead of at the top-level.

Note: This option does not effect where the main service worker JavaScript file is created. That is determined by the swDest option.

Example:

// Use a 'wb-assets' directory for Workbox's assets,
// under the top-level output directory.
importsDirectory: 'wb-assets'

precacheManifestFilename

Optional String, defaulting to 'precache-manifest.[manifestHash].js'

Workbox automatically creates a JavaScript file that contains information about URLs that need to be precached. By default, this file is called precache-manifest.[manifestHash].js, where [manifestHash] is automatically replaced by a unique value that identifies the contents of the file.

precacheManifestFilename can be used to override this default filename. You must include the string [manifestHash] somewhere as part of the filename.

If you'd like to change the output directory to which the precache manifest is written, you can configure the importsDirectory option.

Example:

precacheManifestFilename: 'wb-manifest.[manifestHash].js'
These options configure behavior unrelated to the webpack compilation.

importWorkboxFrom

Optional String, defaulting to 'cdn'

Valid values are 'cdn', 'local', and 'disabled.

  • 'cdn', the default, will use a URL for the Workbox runtime libraries hosted on a highly-available Google Cloud Storage instance.
  • 'local' will copy all of the Workbox runtime libraries into a versioned directory alongside your generated service worker, and configure the service worker to use those local copies. This option is provided for developers who would prefer to host everything themselves and not rely on the Google Cloud Storage CDN.
  • 'disabled' will opt-out automatic behavior. It's up to you to host a local copy of the Workbox libraries at your preferred URL, and to pass in the correct path to workbox-sw.js via the importScripts configuration option.
  • Note: In webpack, passing in a string corresponding to the webpack chunk name containing a custom Workbox runtime library bundle is also supported.

Example:

importWorkboxFrom: 'local'

skipWaiting

Optional Boolean, defaulting to false

Whether or not the service worker should skip over the waiting lifecycle stage. Normally this is used with `clientsClaim: true`.

Example:

skipWaiting: true

clientsClaim

Optional Boolean, defaulting to false

Whether or not the service worker should start controlling any existing clients as soon as it activates.

Example:

clientsClaim: true

runtimeCaching

Optional Array of Object, defaulting to []

Passing in an array of objects containing urlPatterns, handlers, and potentially options will add the appropriate code to the generated service worker to handle runtime caching.

Requests for precached URLs that are picked up via globPatterns are handled by default, and don't need to be accommodated in runtimeCaching.

The handler values are strings, corresponding to names of the strategies supported by workbox.strategies.

The options properties can be used to configure instances of the cache expiration, cacheable response, and broadcast cache update plugins to apply to a given route.

Example:

runtimeCaching: [{
    // Match any same-origin request that contains 'api'.
    urlPattern: /api/,
    // Apply a network-first strategy.
    handler: 'networkFirst',
    options: {
      // Fall back to the cache after 10 seconds.
      networkTimeoutSeconds: 10,
      // Use a custom cache name for this route.
      cacheName: 'my-api-cache',
      // Configure custom cache expiration.
      expiration: {
        maxEntries: 5,
        maxAgeSeconds: 60,
      },
      // Configure which responses are considered cacheable.
      cacheableResponse: {
        statuses: [0, 200],
        headers: {'x-test': 'true'},
      },
      // Configure the broadcast cache update plugin.
      broadcastUpdate: {
        channelName: 'my-update-channel',
      },
      // Add in any additional plugin logic you need.
      plugins: [
        {cacheDidUpdate: () => /* custom plugin code */}
      ],
    },
  }, {
    // To match cross-origin requests, use a RegExp that matches
    // the start of the origin:
    urlPattern: new RegExp('^https://cors\.example\.com/'),
    handler: 'staleWhileRevalidate',
    options: {
      cacheableResponse: {
        statuses: [0, 200]
      }
    }
  }]

navigateFallback

Optional String, defaulting to undefined

This will be used to create a NavigationRoute that will respond to navigation requests for URLs that that aren't precached.

This is meant to be used in a Single Page App scenario, in which you want all navigations to use common App Shell HTML.

It's not intended for use as a fallback that's displayed when the browser is offline.

Example:

navigateFallback: '/app-shell'

navigateFallbackBlacklist

Optional Array of RegExp, defaulting to []

An optional array of regular expressions that restricts which URLs the configured navigateFallback behavior applies to.

This is useful if only a subset of your site's URLs should be treated as being part of a Single Page App.

If both navigateFallbackBlacklist and navigateFallbackWhitelist are configured, the blacklist takes precedent.

Example:

// Exempt all URLs that start with /_ or contain admin anywhere:
navigateFallbackBlacklist: [/^\/_/, /admin/]

navigateFallbackWhitelist

Optional Array of RegExp, defaulting to []

An optional array of regular expressions that restricts which URLs the configured navigateFallback behavior applies to.

This is useful if only a subset of your site's URLs should be treated as being part of a Single Page App.

If both navigateFallbackBlacklist and navigateFallbackWhitelist are configured, the blacklist takes precedent.

Example:

// Include URLs that start with /pages:
navigateFallbackWhitelist: [/^\/pages/]

importScripts

Required Array of String

An required list of JavaScript files that should be passed to importScripts() inside the generated service worker file.

If one of the imported files sets the self.__precacheManifest variable to an array of ManifestEntrys, those entries will be automatically precached in the generated service worker.

This is also useful when you want to let Workbox create your top-level service worker file, but want to include some additional code, such as a push event listener.

Example:

importScripts: ['push-notifications.abcd1234.js']

ignoreUrlParametersMatching

Optional Array of RegExp, defaulting to [/^utm_/]

Any search parameter names that match against one of the regex's in this array will be removed before looking for a precache match.

This is useful if your users might request URLs that contain, for example, URL parameters used to track the source of the traffic. Those URL parameters would normally cause the cache lookup to fail, since the URL strings used as cache keys would not be expected to include them.

Example:

// This will ignore all parameters:
ignoreUrlParametersMatching: [/./]

directoryIndex

Optional String, defaulting to index.html

If a navigation request for a URL ending in / fails to match a precached URL, this value will be appended to the URL and that will be checked for a precache match.

This should be configured to whatever your web server is using, if anything, for its directory index.

Example:

directoryIndex: 'index.html'

cacheId

Optional String, defaulting to null

An optional ID to be prepended to cache names used by Workbox.

This is primarily useful for local development where multiple sites may be served from the same http://localhost:port origin.

Example:

cacheId: 'my-app'

globDirectory

Optional String, defaulting to undefined

The base directory you wish to match globPatterns against, relative to the current working directory.

If you do set this, make sure to also configure globPatterns.

Example:

// Treat all patterns as relative to the current directory:
globDirectory: '.'

globFollow

Optional Boolean, defaulting to true

Determines whether or not symlinks are followed when generating the precache manifest.

For more information, see the definition of follow in the glob documentation.

Example:

globFollow: false

globIgnores

Optional Array of String, defaulting to ['node_modules/**/*']

A set of patterns matching files to always exclude when generating the precache manifest.

For more information, see the definition of ignore in the glob documentation.

Example:

globIgnores: ['**/ignored.html']

globPatterns

Optional Array of String, defaulting to either ['**/*.{js,css,html}'] (for workbox-build and workbox-cli) or [] (for workbox-webpack-plugin)

Files matching against any of these patterns will be included in the precache manifest.

For more information, see the glob primer.

Note: Setting globPatterns is often unnecessary when using the workbox-webpack-plugin, which will automatically precache files that are part of the webpack build pipeline by default. When using the webpack plugin, only set it when you need to cache non-webpack assets.

Example:

globPatterns: ['dist/*.{js,png,html,css}']

globStrict

Optional Boolean, defaulting to true

If true, an error reading a directory when generating a precache manifest will cause the build to fail. If false, the problematic directory will be skipped.

For more information, see the definition of strict in the glob documentation.

Example:

globStrict: false

templatedUrls

Optional Object with String or Array of String values, defaulting to null

If a URL is rendered generated based on some server-side logic, its contents may depend on multiple files or on some other unique string value.

If used with an array of strings, they will be interpreted as glob patterns, and the contents of any files matching the patterns will be used to uniquely version the URL.

If used with a single string, it will be interpreted as unique versioning information that you've generated out of band for a given URL.

Example:

templatedUrls: {
  '/app-shell': [
    'dev/templates/app-shell.hbs',
    'dev/**/*.css',
    ],
  '/other-page': 'my-version-info',
}

maximumFileSizeToCacheInBytes

Optional Number, defaulting to 2097152

This value can be used to determine the maximum size of files that will be precached. This prevents you from inadvertantly precaching very large files that might have accidentally matched one of your patterns.

Example:

// Increase the limit to 4mb:
maximumFileSizeToCacheInBytes: 4 * 1024 * 1024

dontCacheBustUrlsMatching

Optional RegExp, defaulting to null

Assets that match this regex will be assumed to be uniquely versioned via their URL, and exempted from the normal HTTP cache-busting that's done when populating the precache.

While not required, it's recommended that if your existing build process already inserts a [hash] value into each filename, you provide a RegExp that will detect those values, as it will reduce the amount of bandwidth consumed when precaching.

Example:

dontCacheBustUrlsMatching: /\.\w{8}\./

modifyUrlPrefix

Optional Object with String values, defaulting to null

A mapping of prefixes that, if present in an entry in the precache manifest, will be replaced with the corresponding value.

This can be used to, for example, remove or add a path prefix from a manifest entry if your web hosting setup doesn't match your local filesystem setup.

As an alternative with more flexibility, you can use the manifestTransforms option and provide a function that modifies the entries in the manifest using whatever logic you provide.

Example:

modifyUrlPrefix: {
  // Remove a '/dist' prefix from the URLs:
  '/dist': ''
}

manifestTransforms

Optional Array of ManifestTransform, defaulting to null

One or more ManifestTransform functions, which will be applied sequentially against the generated manifest.

If modifyUrlPrefix or dontCacheBustUrlsMatching are also specified, their corresponding transformations will be applied first.

Example:

manifestTransforms: [
  // Basic transformation to remove a certain URL:
  (entries) => entries.filter((entry) => entry.url !== 'ignored.html')
]

InjectManifest Plugin

You can add the InjectManifest plugin to your webpack config like so:

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      swSrc: './src/sw.js',
    })
  ]
};

This will create a precache manifest (a list of webpack assets) and inject it into your service worker file via importScripts().

Full InjectManifest Config

You can pass the appropriate configuration as properties of an Object to the plugin's constructor.

For example:

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({option: 'value'})
  ]
};
These options are specifically for the webpack compilation.

swDest

Optional String, defaulting to `'service-worker.js'`

The path and filename of the service worker file that will be created by the build process, relative to the webpack output directory.

Example:

swDest: 'custom-sw-name.js'

importWorkboxFrom

Optional String, defaulting to 'cdn'

Valid values are 'cdn', 'local', and 'disabled.

  • 'cdn', the default, will use a URL for the Workbox runtime libraries hosted on a highly-available Google Cloud Storage instance.
  • 'local' will copy all of the Workbox runtime libraries into a versioned directory alongside your generated service worker, and configure the service worker to use those local copies. This option is provided for developers who would prefer to host everything themselves and not rely on the Google Cloud Storage CDN.
  • 'disabled' will opt-out automatic behavior. It's up to you to host a local copy of the Workbox libraries at your preferred URL, and to pass in the correct path to workbox-sw.js via the importScripts configuration option.
  • Note: In webpack, passing in a string corresponding to the webpack chunk name containing a custom Workbox runtime library bundle is also supported.

Example:

importWorkboxFrom: 'local'

chunks

Optional Array of String, defaulting to []

By default, Workbox will precache assets regardless of which chunk the asset is part of.

If you would like to override this behavior via a whitelist, specify one or more chunk names. Only assets belonging to those chunks will be precached; any assets belonging to another chunk or without a chunk association will be skipped.

Example:

// *Only* include assets that belong to these chunks:
chunks: ['chunk-name-1', 'chunk-name-2']

excludeChunks

Optional Array of String, defaulting to []

By default, Workbox will precache all assets generated by the webpack compilation, regardless of which chunk the asset is part of.

If you would like to override this behavior via a blacklist, specify one or more chunk names. Any assets belonging to those chunks will be skipped.

Example:

// Exclude assets that belong to these chunks:
excludeChunks: ['chunk-name-1', 'chunk-name-2']

include

Optional Array of RegExp or String

This allows you to only include assets matching any of the provided criteria when creating the precache manifest. It provides a filename-based approach to filtering.

This filtering takes place after any chunk-based filtering is applied.

In keeping with webpack convention, the option `test` can be used as an alias/alternative to `include`.

Example:

// Only include HTML and JS assets when precaching:
include: [/\.html$/, /\.js$/]

exclude

Optional Array of RegExp or String, defaulting to [/\.map$/, /^manifest.*\.js(?:on)?$/]

This allows you to specifically omit assets matching any of the provided criteria from being included in the precache manifest. It provides a filename-based approach to filtering.

This filtering takes place after any chunk-based filtering is applied.

Example:

// Exclude JPG and PNG assets from precaching:
exclude: [/\.jpg$/, /\.png$/]

importsDirectory

Optional String, defaulting to ''

Workbox creates assets as part of your webpack build process: a precache manifest file, and potentially a local copy of the Workbox libraries (if importWorkboxFrom is set to 'local').

These assets will, by default, be created at the root of your webpack build directory, i.e. output.path. You can set the importsDirectory option if you want these assets to be created in a subdirectory of output.path instead of at the top-level.

Note: This option does not effect where the main service worker JavaScript file is created. That is determined by the swDest option.

Example:

// Use a 'wb-assets' directory for Workbox's assets,
// under the top-level output directory.
importsDirectory: 'wb-assets'

precacheManifestFilename

Optional String, defaulting to 'precache-manifest.[manifestHash].js'

Workbox automatically creates a JavaScript file that contains information about URLs that need to be precached. By default, this file is called precache-manifest.[manifestHash].js, where [manifestHash] is automatically replaced by a unique value that identifies the contents of the file.

precacheManifestFilename can be used to override this default filename. You must include the string [manifestHash] somewhere as part of the filename.

If you'd like to change the output directory to which the precache manifest is written, you can configure the importsDirectory option.

Example:

precacheManifestFilename: 'wb-manifest.[manifestHash].js'
These options configure behavior unrelated to the webpack compilation.

swSrc

Required String

The path to the source service worker file that can contain your own customized code, in addition to containing a match for injectionPointRegexp.

In Node

Your service worker file should include a call to a workbox.precaching method that makes use of the injected precache manifest.

In Webpack

Your service worker file should reference the self.__precacheManifest variable to obtain a list of ManifestEntrys obtained as part of the compilation: workbox.precaching.precacheAndRoute(self.__precacheManifest)

Example:

swDest: path.join('src', 'sw.js')

globDirectory

Optional String, defaulting to undefined

The base directory you wish to match globPatterns against, relative to the current working directory.

If you do set this, make sure to also configure globPatterns.

Example:

// Treat all patterns as relative to the current directory:
globDirectory: '.'

globFollow

Optional Boolean, defaulting to true

Determines whether or not symlinks are followed when generating the precache manifest.

For more information, see the definition of follow in the glob documentation.

Example:

globFollow: false

globIgnores

Optional Array of String, defaulting to ['node_modules/**/*']

A set of patterns matching files to always exclude when generating the precache manifest.

For more information, see the definition of ignore in the glob documentation.

Example:

globIgnores: ['**/ignored.html']

globPatterns

Optional Array of String, defaulting to either ['**/*.{js,css,html}'] (for workbox-build and workbox-cli) or [] (for workbox-webpack-plugin)

Files matching against any of these patterns will be included in the precache manifest.

For more information, see the glob primer.

Note: Setting globPatterns is often unnecessary when using the workbox-webpack-plugin, which will automatically precache files that are part of the webpack build pipeline by default. When using the webpack plugin, only set it when you need to cache non-webpack assets.

Example:

globPatterns: ['dist/*.{js,png,html,css}']

globStrict

Optional Boolean, defaulting to true

If true, an error reading a directory when generating a precache manifest will cause the build to fail. If false, the problematic directory will be skipped.

For more information, see the definition of strict in the glob documentation.

Example:

globStrict: false

templatedUrls

Optional Object with String or Array of String values, defaulting to null

If a URL is rendered generated based on some server-side logic, its contents may depend on multiple files or on some other unique string value.

If used with an array of strings, they will be interpreted as glob patterns, and the contents of any files matching the patterns will be used to uniquely version the URL.

If used with a single string, it will be interpreted as unique versioning information that you've generated out of band for a given URL.

Example:

templatedUrls: {
  '/app-shell': [
    'dev/templates/app-shell.hbs',
    'dev/**/*.css',
    ],
  '/other-page': 'my-version-info',
}

maximumFileSizeToCacheInBytes

Optional Number, defaulting to 2097152

This value can be used to determine the maximum size of files that will be precached. This prevents you from inadvertantly precaching very large files that might have accidentally matched one of your patterns.

Example:

// Increase the limit to 4mb:
maximumFileSizeToCacheInBytes: 4 * 1024 * 1024

dontCacheBustUrlsMatching

Optional RegExp, defaulting to null

Assets that match this regex will be assumed to be uniquely versioned via their URL, and exempted from the normal HTTP cache-busting that's done when populating the precache.

While not required, it's recommended that if your existing build process already inserts a [hash] value into each filename, you provide a RegExp that will detect those values, as it will reduce the amount of bandwidth consumed when precaching.

Example:

dontCacheBustUrlsMatching: /\.\w{8}\./

modifyUrlPrefix

Optional Object with String values, defaulting to null

A mapping of prefixes that, if present in an entry in the precache manifest, will be replaced with the corresponding value.

This can be used to, for example, remove or add a path prefix from a manifest entry if your web hosting setup doesn't match your local filesystem setup.

As an alternative with more flexibility, you can use the manifestTransforms option and provide a function that modifies the entries in the manifest using whatever logic you provide.

Example:

modifyUrlPrefix: {
  // Remove a '/dist' prefix from the URLs:
  '/dist': ''
}

manifestTransforms

Optional Array of ManifestTransform, defaulting to null

One or more ManifestTransform functions, which will be applied sequentially against the generated manifest.

If modifyUrlPrefix or dontCacheBustUrlsMatching are also specified, their corresponding transformations will be applied first.

Example:

manifestTransforms: [
  // Basic transformation to remove a certain URL:
  (entries) => entries.filter((entry) => entry.url !== 'ignored.html')
]

Cache additional, non-webpack assets

By default, both plugins generate a precache manifest that contains URLs for assets created by the current webpack compilation. Any assets that webpack doesn't "know" about will not be picked up.

If you need to precache additional assets that are managed outside of webpack, then you can use the globDirectory and globPatterns options to specify how to find those additional assets.

If you decide to use globDirectory and globPatterns, the following applies:

  • The glob pattern matching will be performed against the local file system, and the directory that globDirectory is set to must exist at the time the plugin runs. This might run afoul of webpack-dev-server configurations, where an in-memory file system is used.
  • The options that work with glob-based precache manifests, like manifestTranforms and modifyUrlPrefix, can also be used, but they'll apply only to the entries that are matched via glob patterns, and not to any assets that are picked up via the webpack compilation.

Extra Info

Guidance on using the plugins within the context of a larger webpack build can be found in the "Progressive Web Application" section of the webpack documentation.