workbox

Workbox is a collection of JavaScript libraries for Progressive Web Apps

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.

dev

(Boolean) Enable workbox in dev mode of nuxt. (Disabled by default - Not recommended)

IMPORTANT NOTE: Remember to clean application data and unregister service workers in your browser or you will experience infinity loop!

It is recommended to test workbox using nuxt build/nuxt start. You can enable debug mode using workbox.config.debug.

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',
         cacheExpiration: {
           maxEntries: 10,
           maxAgeSeconds: 300
         }
       }
     }
   ]
}

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.js:

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: [
    {
      src: '~/plugins/sw.js',
      ssr: false
    }
  ]
}

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.Plugin(),
    ],
  }),
  '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.
    }
  });
}