The plugin brings enhanced PWA support to VuePress .
# Content caching and updating
Service Worker  (SW for short) is mainly used to cache and proxy site content.
This plugin will automatically register Service Woker through
To better control what the Service Worker can pre-cache, the plugin provides the following configurations.
If you are an advanced user, you can also directly set
generateSwConfig to pass options to
# Default cache
By default, the plugin will pre-cache all files related to the site:
At the same time, the plugin will cache font files:
# Cache Control
Based on the requirement of installable , the plugin provides related options for cache control.
# Picture Cache
You can cache site pictures by setting the
cachePic option to
If your site is not large and the pictures are mostly critical descriptions, and hope to be displayed in offline mode, please set this option to
We recognize images by file extension. Any files ending with
.webp will be regarded as images.
# HTML cache
When your site is too large, you can set
false to cache only the homepage and 404 error pages.
Why can these be removed?
VuePress is essentially a SPA. This means that you can enter from the homepage to access all pages normally only caching the homepage.
When your site has a large number of pages or content, and the volume is too large after including HTML files, you can consider setting this option to
false, which can reduce the volume by about 40%. The disadvantage is that users can only enter through the homepage and then navigate to the corresponding page in an offline environment. Direct access to a link will prompt a web page error.
# Size control
To prevent large files from being included in the pre-cache list, any files larger than 2MB or pictures larger than 1MB will be deleted.
You can customize the maximum file size of the cache (unit: KB) with the
maxSize option, or change the size limit of the picture (unit: KB) with
# Update popup
We provide an update popup when new content is successfully downloaded.
If you are not satisfied with the default popup component, you can write component and replace it by yourself. To do that, You need to register your popup component globally and pass the name of the component to the
# Manifest file generation
To ensure the installability of PWA, the site needs to generate a manifest file and declare a valid manifest file address  through
The plugin will automatically generate the Manifest file
manifest.webmanifest for you in the output directory, and will also add the manifest address statement to each HTML
If you already have a
.vuepress/public, the plugin will read and merge it into the final manifest.
# Automatic generation
The plugin will use the information from the VuePress plugin API and set the fallback for fields in manifest as much as possible. So you don’t need to set most of the manifest fields.
If the following fields are not set, they will try to fallback to the following preset values in order.
For complete configuration items, please see Manifest Type Definition File (opens new window)
# Manual configuration
You can manually specify the contents of the manifest in the
manifest option has the highest priority, followed by manifest files that may exist in the
You should at least set a valid icon through
manifest.icons or other icon related options in the PWA plugin.
The installability [3:1] specification requires at least one valid icon to be declared in the manifest.
So if you do not configure
manifest.icons, visitors can only enjoy the offline accessibility brought by the Service Worker cache, while cannot install your site as a PWA.
Besides the plugin does not process anything in the manifest, but outputs them as-is. This means that if you plan to deploy to a subdirectory, you should add
base to the corresponding URL in the manifest yourself.
# Other options
The plug-in also provides other PWA-related options, such as Microsoft tile icon and color settings, Apple icon and so on.
You can set them as needed. For detailed options, please see Configuration Page.
# Further Reading
For more details, please see:
- Google PWA (opens new window)
- MDN PWA (opens new window)
- W3C Manifest Specification (opens new window)
PWA, full name Progressive Web app. PWA standard is stipulated by W3C.
It allows sites to install the site as an App on supported platform through a browser that supports this feature. ↩︎
Service Worker Introduction
The Service Worker will get and cache all the files registered in it during the registration process.
After the registration complete, the Service Worker is activated, and starts to proxy and control all your requests.
Whenever you want to initiate an access request through the browser, the Service Worker will check whether it exists in its own cache list, if it exists, it will directly return the cached result, otherwise it will call its own fetch method to get it. You can use a custom fetch method to fully control the result of the request for resources in the webpage, such as providing a fallback webpage when offline.
Every time the user reopens the site, the Service Worker will request to the link when it was registered. If a new version of Service Woker is detected, it will update itself and start caching the list of resources registered in the new Service Worker . After the content update is successfully obtained, the Service Worker will trigger the
updateevent. The user can be notified through this event, for example, a pop-up window will be displayed in the lower right corner, prompting the user that new content is available and allowing the user to trigger an update.
To let the site be registered as a PWA, the site needs to successfully register a valid service worker by itself, and at the same time add a valid manifest file and declare it.
Each platform or browser has requirements for the size of the Service Worker cache. When the file size of the Service Worker cache is too large, the site will be marked as not installable. For Safari, the threshold is 50 MB, a few browsers will set less or more values (30MB, 70MB, 80MB), and Chrome will mark the threshold at 100 MB.
The manifest file should contain at least
SSR: Server Side Rendering, ↩︎
SPA: Single Page Application, mMost of them only have the homepage, and use history mode to handle routing instead of actually navigating between pages. ↩︎
The manifest file uses the JSON format and is responsible for declaring various information of the PWA, such as name, description, icon, and shortcut actions.
In order for your site to be registered as a PWA, you need to meet the basic specifications of the manifest to make the browser consider the site as an installable PWA and allow users to install it.↩︎
For Manifest standards and specifications, please see W3C Manifest (opens new window)