pwa

Make your VuePress site a Progressive Web Application (PWA).

This plugin uses workbox-build to generate service worker file, and uses register-service-worker to register service worker.

Usage

npm i -D @vuepress/plugin-pwa@next

import { pwaPlugin } from '@vuepress/plugin-pwa'

export default {
  plugins: [
    pwaPlugin({
      // options
    }),
  ],
}

Web App Manifests

To make your website fully compliant with PWA, you need to create a Web app manifests file and set the icons, colors, etc. for your PWA.

You need to put your manifest file and icons into the public files directory. In the following example, we assume that you are using the default public directory .vuepress/public.

1. Create manifest file

Typically .vuepress/public/manifest.webmanifest:

{
  "name": "VuePress",
  "short_name": "VuePress",
  "description": "Vue-powered Static Site Generator",
  "start_url": "/index.html",
  "display": "standalone",
  "background_color": "#fff",
  "theme_color": "#3eaf7c",
  "icons": [
    {
      "src": "/images/icons/android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/images/icons/android-chrome-384x384.png",
      "sizes": "384x384",
      "type": "image/png"
    }
  ]
}

2. Generate PWA icons

To make your PWA more accessible, you need to generate some icons, and put them inside the public directory.

Make sure the path of icons matches the icons field in your manifest file:

• .vuepress/public/images/icons/android-chrome-192x192.png
• .vuepress/public/images/icons/android-chrome-384x384.png

TIP

Some tools can help to do that. For example, Favicon Generator would help you to generate icons together with a sample manifest file.

3. Set tags in head

You also need to set some tags via head option to deploy the manifest:

export default {
  head: [
    ['link', { rel: 'manifest', href: '/manifest.webmanifest' }],
    ['meta', { name: 'theme-color', content: '#3eaf7c' }],
    // ...other tags
  ],
}

Options

This plugin accepts all parameters of workbox-build's generateSW method in its options, except globDirectory and swDest.

For example, you can set skipWaiting: true to auto activate the new service worker once it is ready:

export default {
  plugins: [
    pwaPlugin({
      skipWaiting: true,
    }),
  ],
}

But if you omit skipWaiting or set it to false, you have to activate the new service worker manually:

• For users, you can use our pwa-popup plugin together.
• For developers, you can use our composition API to take control of the service worker behavior.

serviceWorkerFilename

• Type: string

• Default: 'service-worker.js'

• Details:

  File path of the generated service worker file, which is relative to the dest directory.

  The service worker file will only be generated in build mode.

Composition API

usePwaEvent

• Details:

  Returns the event emitter of this plugin.

  You can add listener function to events that provided by register-service-worker.

• Example:

import { usePwaEvent } from '@vuepress/plugin-pwa/client'

export default {
  setup() {
    const event = usePwaEvent()
    event.on('ready', (registration) => {
      console.log('Service worker is active.')
    })
  },
}

useSkipWaiting

• Parameters:

Parameter	Type	Description
registration	ServiceWorkerRegistration	The registration of the service worker you want activate

• Details:

  Call skipWaiting() to activate the waiting service worker.

• Example:

import { usePwaEvent, useSkipWaiting } from '@vuepress/plugin-pwa/client'

export default {
  setup() {
    const event = usePwaEvent()
    event.on('updated', (registration) => {
      console.log('The waiting service worker is available.')
      // activate the waiting service worker
      useSkipWaiting(registration)
    })
  },
}