Workbox Module

Workbox is a collection of JavaScript libraries for Progressive Web Apps. (Learn more). This module adds full offline support using workbox.

You can pass options to pwa.workbox in nuxt.config.js to override the defaults.

pwa: {
  workbox: {
    /* workbox options */
  }
}

Options

workboxVersion

(String) Version of workbox. Default value is latest tested version which will be updated by updating this package.

workboxURL

(String) URL for workbox CDN. Default is JSDelivr - See Workbox CDN. You can also use config.modulePathPrefix if you need to rewrite module paths.

importScripts

(Array) Additional scripts to be imported in service worker script. (Relative to /. Can be placed in assets/ directory)

autoRegister

(Boolean) Automatically register /sw.js on page load. Enabled by default.

enabled

(Boolean) Enable workbox module. Workbox is only enabled for production mode by default.

IMPORTANT NOTES:

• It is recommended to test workbox using nuxt build/nuxt start. You can enable debug mode using workbox.config.debug for production to debug.
• When setting enabled to true, remember to clean application data and unregister service workers in your browser when changing mode between dev or prod to avoid issues.
• When enabled is set to false (default for nuxt dev) workbox module registers a self-destroying worker and cleans window.caches. To completely disable module you can set pwa.workbox: false in nuxt.config.

cacheNames

(Object) Configure the workbox cache names. See workbox docs for more information on this.

config

(Object) Options to be passed to workbox before using it's modules. By default debug field will be set to false for production builds.

clientsClaim

(Boolean) Start controlling any existing clients as soon as it activates. Enabled by default.

skipWaiting

(Boolean) Skip over the SW waiting lifecycle stage. Enabled by default.

offlineAnalytics

(Boolean) Enable offline Google Analytics tracking through workbox (Disabled by default)

workboxExtensions

(String|String[]) Loads and inserts the contents of the specified file path into the service worker script before any call to precacheAndRoute. You may add as many extra calls as you want to these files.

preCaching

(Array) Cache a set of files when registering service worker. Default is []

Workbox takes a lot of the heavy lifting out of precaching by simplifying the API and ensuring assets are downloaded efficiently.

cacheOptions

(Object) Default:

{
  cacheId: '<npm package name> || nuxt',
  directoryIndex: '/',
  revision: undefined
}

cachingExtensions

(String|String[]) Loads and inserts the contents of the specified file path into the service worker script, below autogenerated calls to workbox.precaching.*. You may add as many extra calls as you want to these files.

cleanupOutdatedCaches

(Boolean) Find and remove any of the older precaches that might have been used by previous versions of Workbox.

offline

(Boolean) Cache all routes. Enabled by default.

offlineStrategy

(String) Strategy for caching routes. Default is NetworkFirst.

offlinePage

(String) Enables routing all offline requests to the specified path. (Example: /offline.html)

Please note that enabling offlinePage will disable /.* caching (offline option) and will route all offline requests to the specified path.

offlineAssets

(Array) List of assets to precache, in case you need extra files precached other than on the fly caching (_nuxt/* etc) or you want to ensure assets used by your offlinePage. (Example: ['/offline.png'])

runtimeCaching

(Array) Custom routes to cache with specific strategy. Useful for caching requests to other origins.

cacheAssets

(Boolean) Cache requests to the /_nuxt/* with CacheFirst strategy on the fly. Enabled by default.

NOTE: This is considered safe because all assets should be correctly hashed there.

NOTE: Nuxt smart links trigger chunk downloads for next pages when user sees a link to a non-cached page.

routingExtensions

(String|String[]) Loads and inserts the contents of the specified file path into the service worker script, below autogenerated calls to workbox.routing.*. You may add as many extra calls as you want to these files.

assetsURLPattern

(String/Regex) Pattern to match assets for runtime caching.

Default is auto generated based on publicPath. Supports CDN too.

Default: /_nuxt/

pagesURLPattern

(String/Regex) Pattern to match pages to be offlined.

Default is auto generated based on router.base.

Default: /

swTemplate

(String) You can use this to customize generated sw.js. Not recommended to be directly used.

swURL

(String) If you need to register another service worker (OneSignal, etc) you can use this option.

swDest

(String) If you want to change the name of service worker, you must use this option with swURL.

swScope

(String) Defaults to routerBase.

routerBase

(String) Defaults to router base.

publicPath

(String) Defaults to /_nuxt.

Workbox Window

This module uses workbox-window to register and communicate with workbox service worker. See docs for more information about use cases.

As service worker is registered in background, to access instance you have to await on a promise:

const workbox = await window.$workbox

if (workbox) {
  // Service worker is available
}

Examples

Adding custom runtimeCaching items (For CDN)

By default resources in dist (/_nuxt/) will be cached with CacheFirst and other requests to same domain will be cached with NetworkFirst strategy.

If you have a custom CDN and need to cache requests for it, simply use runtimeCaching:

IMPORTANT: Please note that workbox will not cache opaque responses. So please only use either NetworkFirst or StaleWhileRevalidate strategies. Please see Handle Third Party Requests.

workbox: {
      runtimeCaching: [
      {
        // Should be a regex string. Compiles into new RegExp('https://my-cdn.com/.*')
        urlPattern: 'https://my-cdn.com/.*',
        // Defaults to `NetworkFirst` if omitted
        // handler: 'NetworkFirst',
        // Defaults to `GET` if omitted
        // method: 'GET'
      }
    ]
}

Adding custom cache

StrategyOption

workbox: {
   runtimeCaching: [
     {
       urlPattern: 'https://my-cdn.com/posts/.*',
       strategyOptions: {
         cacheName: 'our-cache',
       },
       strategyPlugins: [{
          use: 'Expiration',
          config: {
            maxEntries: 10,
            maxAgeSeconds: 300
          }
        }]
     }
   ]
}

This strategy plugins are supported (possible values for strategyPlugins[].use):

• BackgroundSync
• BroadcastUpdate
• CacheableResponse
• Expiration
• RangeRequests

You can pass an array for strategyPlugins[].config if it supports more than one argument. Only JSON serializable values are supported (for example you cannot pass an inline function as config)

Adding custom service worker

Create static/custom-sw.js file:

console.log('Custom service worker!')

Add it with importScripts option in nuxt.config.js:

workbox: {
  importScripts: [
      'custom-sw.js'
  ],
}

Hooking on service worker registration life cycle

Create plugins/sw.client.js. The client suffix tells Nuxt that the plugin should only be loaded on client-side:

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.getRegistrations().then((registrations) => {
    for (const worker of registrations) {
      console.log('Service worker:', worker)
    }
  });
}

Add it to the plugins section of nuxt.config.js:

{
  plugins: [
    '~/plugins/sw.client.js'
  ]
}

Basic Auth

As a workaround for making basic auth working as described here you have to enable manifest.crossorigin in nuxt.config.js:

{
  manifest: {
    crossorigin: 'use-credentials'
  }
}

Thanks to @henrixapp for the tip.

Enable rangeRequests

Safari requires rangeRequests.

plugins/workbox-range-request.js:

workbox.routing.registerRoute(
  /\.(mp4|webm)/,
  new workbox.strategies.CacheFirst({
    plugins: [
      new workbox.rangeRequests.RangeRequestsPlugin(),
    ],
  }),
  'GET'
);

nuxt.config.js:

{
  workbox: {
    cachingExtensions: '@/plugins/workbox-range-request.js'
  }
}

Thanks to @CarterLi for the tip.

Disable Add to Home Screen button (the mini-infobar)

A PWA can be installed by the user if it meets a set of criteria and as installable it can trigger an "Add to Home Screen" button (the mini-infobar) as described here.

One criteria is that display must be either fullscreen, standalone, or minimal-ui. If you want to prevent the mini-infobar from appearing in your App, you can set the pwa.manifest.display to browser in nuxt.config.js:

{
  pwa {
   manifest: {
      display: 'browser'
    }
  }
}

Refresh to Update Notification

In layouts/default.vue (or wherever you want, maybe in a plugin):

const workbox = await window.$workbox;
if (workbox) {
  workbox.addEventListener('installed', (event) => {
    // If we don't do this we'll be displaying the notification after the initial installation, which isn't perferred.
    if (event.isUpdate) {
      // whatever logic you want to use to notify the user that they need to refresh the page.
    }
  });
}