# workbox

Workbox is a collection of JavaScript libraries for Progressive Web Apps. ([Learn more](https://developers.google.com/web/tools/workbox)). This module adds full offline support using workbox.

You can pass options to `pwa.workbox` in `nuxt.config.js` to override the [defaults](https://github.com/nuxt-community/pwa-module/blob/dev/lib/workbox/defaults.js).

```
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](https://github.com/nuxt-community/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](https://developers.google.com/web/tools/workbox/guides/configure-workbox#configure_cache_names) 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](https://developers.google.com/web/tools/workbox/guides/enable-offline-analytics) (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:

```javascript
{
  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](https://developers.google.com/web/tools/workbox/modules/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:

```javascript
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](https://developers.google.com/web/tools/workbox/guides/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](https://developers.google.com/web/tools/workbox/modules/workbox-strategies)

```
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](https://thatemil.com/blog/2018/02/21/pwa-basic-auth) you have to enable `manifest.crossorigin` in `nuxt.config.js`:

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

Thanks to [@henrixapp](https://github.com/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](https://github.com/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](https://developers.google.com/web/fundamentals/app-install-banners/).

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.
    }
  });
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nuxt-community.gitbook.io/pwa/dev/docs/content/en/workbox.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.