README

@gasket/plugin-workbox

Provides precaching and runtimeCaching via Workbox.

Precaching downloads an app's pages, chunks, and assets and stores this on the device, before they are actually needed. This happens asynchronously and results in a faster experience. Additionally, other files and be cached with on-demand strategies, such as cacheFirst, or networkFirst.

This plugin implements service worker configuration using Workbox. Workbox is a library that bakes in a set of best practices and removes the boilerplate every developer writes when working with service workers.

Installation

New apps

gasket create <app-name> --plugins @gasket/plugin-workbox

Existing apps

npm i @gasket/plugin-workbox

Modify plugins section of your gasket.config.js:

module.exports = {
  plugins: {
    add: [
+      '@gasket/plugin-workbox'
    ]
  }
}

Configuration

Set the Workbox options, in the gasket.config.js under workbox.

outputDir - (string) path of directory to copy Workbox libraries to (default: ./build/workbox)
basePath - (string) change the default path to /_workbox endpoint by adding a path prefix here. (default: ''). Used for setting up CDN support for Workbox files.
config: (object) Any initial workbox config options which will be merged with those from any workbox lifecycle hooks.

Example config

// gasket.config
module.exports = {
  workbox: {
    config: {
      runtimeCaching: [{
        urlPattern: /.png$/,
        handler: 'cacheFirst'
      }]
    }
  }
}

Lifecycles

workbox

This hook allows other Gasket plugins to add to the Workbox config in order to precache files, set runtime cache rules, etc. Hooks should return an object partial which will be deeply merged.

module.exports = {
  hooks: {
    workbox: function (gasket, config, context) {
      // `config` is the initial workbox config
      // `context` is the service-worker context.
      const { req, res } = context;
      if(req) {
        // adjust config for request-based service workers using headers, cookies, etc.
      }

      // return a config partial which will be merged
      return {
        runtimeCaching: [{
          urlPattern: /https:\/\/some.api.com/,
          handler: 'networkFirst'
        }]
      }
    }
  }
}

For advanced configurations, be sure to read the workbox config options for generateSWString.

How it works

For a service worker request, a config object is constructed by the Workbox lifecycle hook, it is to generateSWString from the workbox-build module. This will generate a string with service worker code for workbox which is then appended to the service worker content in the composeServiceWorker hook from @gasket/plugin-service-worker.

During the build hook, the Workbox libraries are copied to the build output directory so that they can be served by the app. The service worker will then import these scripts, with requests to the /_workbox static files served by the app. These can be set up to edge cache by setting the basePath option.

License

MIT

Usage no npm install needed!