How to install and configure the PWA Stacks
Quick Links
PWA Stack
Installation
Add the PWA Stack to the top of your home page, before any other stacks.
Advanced Caching Only
To use advanced caching only with the default Cache Strategies, no configuration is neccessary. Just add the PWA Helper Stack to all of your other pages and publish your project.
On first visit to your home page, the Service Worker will be created in your document root.
You can modify the Cache Strategies in the PWA Stack Settings. See below for more information about Cache Strategies.
Important : Any time you make changes to the PWA Stack settings, you should visit your home page to recreate the Service Worker.
Important : To avoid any conflicts, you should disable any server side cache settings, such as in the htaccess file, or the LiteSpeed Expires seting.
PWA Installation
You can make your PWA installable on users desktop and mobile devices. Check the PWA is Installable checkbox to enable this option, and you will be presented with the settings required to create a Web App Manifest file.
The Start Page is optional, but the Offline Page is mandatory.
Use image sizes as specified in the stack settings. Other required sizes are created automatically when you preview or publish the page. This may slow down the preview of your home page on older Macs.
Advanced Usage
Multiple PWAs
While you would typically only add one PWA to your site, you also have the option to add multiple PWAs on one website.
An example of this could be:
- add a PWA to the website for regular users to install.
- add a second PWA to the main Admin page, for the website admin to edit CMS content.
To add a second PWA, the index page must be in a subfolder (e.g. /siteadmin/index.php). Change the Mode to be either Admin, or a custom unique mode name. Configure the second PWA using the same instructions as above.
public_html /
|- index.php (User PWA)
|- offline.php
|- about / index.php
|- blog / index.php
|- contact / index.php
|- siteadmin / index.php (Admin PWA)
|- siteadmin / blog / index.php
|- siteadmin / offline.php
Pre-Caching Resources
There may be resources that are not covered by the existing Cache Strategies. These resources can be pre-cached by checking the Precache additional URLs checkbox.
When the PWA is installable, the Offline Fallback Page is always pre-cached.
See below for additional information about Precaching Resources.
Custom Cache Strategies
There may be pages or paths where you want to apply a different Cache Strategy than what is used on the rest of your site.
For example, if your blog page is constantly changing or being updated, you can add a Custom Cache Strategy that uses a Network First strategy for the html document only. This ensures that the visitor always receives the latest blog page content, but the CSS, Javascript and images are still served from the cache.
See below for additional information about Custom Cache Strategies.
Helper Stack
Not everyone who visits your webpage, visits the home page first, therefore the PWA Helper Stack is required on your other pages to make sure that the Service Worker gets loaded and starts running.
Add the PWA Helper Stack to the top of all your other stacks pages, and set the PWA Stack link to the page where you added the PWA Stack (normally your home page).
If you changed the Mode in your PWA Stack settings, then set the corresponding Mode here.
Offline Page
When you enable installation in the PWA Stack settings, you need to provide a dedicated Offline Fallback Page. This page is pre-cached and displayed when your PWA users connection to the Internet is lost, and they try to navigate to a page that has not yet been stored in the cache.
You should keep your offline page as simple as possible, and provide Back and Refresh buttons. Add the PWA Offline Stack to this page, and disable the Show in navigation setting in the RapidWeaver Page Inspector.
If you are adding more than one PWA to your site, you can use the same offline page for each PWA, or create separate pages.
Important : The offline page should be located in same folder that you installed the PWA Stack. Name the file offline.php or something similar.
public_html /
|- index.php
|- offline.php
|- about / index.php
|- services / index.php
|- contact / index.php
Start Page
The start page is the page that is displayed when the user first opens your PWA on their device. You can set this to the home page, or create a custom start page.
An example of a custom start page is used in the PWA demo project, and shows the latest blog post or news. The start page is also using a custom cache strategy (Network First) so that it always displays the latest content.
Add to Home Screen
On Android devices, an Add to Home Screen message is displayed automatically if the PWA is installable. IOS does not have this capability yet, so you can add the PWA Install Stack to all of your pages.
Add the PWA Install Stack to the bottom of the page so that it loads after everything else.
Cache Strategies
A cache strategy is a pattern that determines how a service worker generates a response after receiving a fetch event.
The PWA Stack comes with 4 cache strategies.
Stale-While-Revalidate
The stale-while-revalidate strategy allows the service worker to respond to the request as quickly as possible with a cached response if available, falling back to the network request if it’s not cached. The network request is then used to update the cache. This strategy will always make a revalidation request, regardless of the age of the cached response.
This is a fairly common strategy where having the most up-to-date resource is not vital to the application.
Cache First
For assets that are non-critical and can be gradually cached, a Cache First strategy is the best option. If there is a response in the cache, the request will be fulfilled using the cached response and the network will not be used at all. If there isn't a cached response, the request will be fulfilled by a network request and the response will be cached so that the next request is served directly from the cache.
Network First
For requests that are updating frequently, the Network First strategy is the ideal solution. By default, it will try to fetch the latest response from the network. If the request is successful, it’ll put the response in the cache. If the network fails to return a response, the cached response will be used.
Network Only
If you require specific requests to be fulfilled from the network, Network Only is the strategy to use.
Custom Strategies
You can set the overall cache strategies in the PWA Stack settings, however you can also fine tune the Service Worker by adding custom cache strategies at the page level.
In the example above, the following custom cache strategies are used:
- Start Page - the index.php (document) is Network First, so that this page always displays the latest HTML. JavaScript, CSS and image caching is unaffected by this custom cache strategy.
- https://demo.rwpro.dev/pwa/start/
- Blog Page - as above, the index.php is Network First. Because the Ends With prefix is used, only the index.php file is affected. Post.php retains the master cache settings from the PWA Stack.
- https://demo.rwpro.dev/pwa/blog/
- https://demo.rwpro.dev/pwa/blog/post.php?permalink=demo-blog-post
- CMS Admin - for our CMS admin pages, the Starts With prefix is used so that the cms-admin folder, and all subfolders, use this custom cache strategy.
- https://demo.rwpro.dev/pwa/cms-admin/
- https://demo.rwpro.dev/pwa/cms-admin/blog/
- https://demo.rwpro.dev/pwa/cms-admin/blog/new-post/
- Gallery - the gallery page uses Cache First so that images are always served from the cache. If the cache responds with a 404 (not found), the image will be requested from the server. This strategy also uses some additional settings:
- Max Entires - the maximum number of gallery images that can be stored in the cache. If this number is reached, images requested the least will be overwritten first. 0 disables this setting.
- Max Age - How long to store each image in the cache before it is deleted. 0 disables this setting.
- Purge - If the cache is full, allow this image cache to be purged. False disables this setting.
Pre-Caching Resources
When the install option is enabled in the PWA Stack, you must create an offline fallback page. This offline page is always pre-chached when the user first visits your website, the offline page has a newer version, or the Service Worker is updated.
You also have the ability to pre-cache any other file or resource that you choose by adding it to the Pre-Cache section of the PWA Stack. I recommend leaving the version on Auto, which uses a timestamp as the version number.
Push Messages
Configuration
Before configuring PWA Push Messages, make sure that your app is set up in Firebase. If you're not sure, visit Introduction to Firebase for details on how to get started.
Go to your Project Settings in the Firebase Console, and under the General tab, you will find your app settings.
Add the PWA Messages Stack to the bottom of your home page. Copy each setting from the Firebase Configuration, and paste it into the corresponding PWA Messages Stack -> Firebase - General setting.
Next, go to the Cloud Messaging tab, and under Web Push Certificates, click on the Generate Key Pair button.
Copy the newly created Key and paste it into the PWA Messages Stack -> Firebase - Cloud Messaging setting.
You should add the PWA Messages Helper Stack to all your other pages. This stack prompts the user to accept Web Push Notifications if they visit your website without going via the homepage.
You can now publish your site and visit the home page (or the page where you installed the PWA Push Messages Stack) to generate the Service Worker. No matter where you install the PWA Push Messages Stack, this Service Worker will be created in your absolute document root folder (e.g. public_html).
Sending Push Messages
You will use the Firebase Console to send push messages to your PWA users. Under the Spark Plan, you can send unlimited push messages for free.
In the left sidebar, under the Engage submenu, click on Cloud Messaging.
If this is your first time, click on the Send your first message button, otherwise you can click on New Notification.
- Notification - Enter the notification title and text and add a name. The name is internal and only used for identification in your notifications list.
- Target - Select the app that will receive the notification.
- Scheduling - Choose when to send your notification.
- Conversion Events - Not in use
- Additional Options
- Android Notification Channel - Not in use
- Custom data - Not in use
- Sound - Enable or disable sound
- Expires - Set how long the message should be kept for redelivery.
Now you can either save the notification as a draft, or click on Review, and then Send.
Receiving Messages
PWA users on Android devices, and Chrome users on desktop devices should be prompted to enable notifications when they first visit your website. If they have accepted, they should receive your notifications sent from the Firebase Console. During testing, notifications arrived anywhere between 1 to 20 minutes after being sent.
Safari is not yet supported, and as Chrome on IOS uses the Safari engine, that won't work either. We eagerly await Apple to follow other browsers in allowing Web Push Messages for PWAs.
If you don't own an Android device to test this out, you can download and install Android Studio. When creating a virtual device in the AVD Manager, make sure you select a device with the Play Store version. There are many tutorials on YouTube about how to install an Android virtual device.
Once your virtual device has started, navigate to your PWA in Chrome and accept notifications.
Stack Settings
- Settings
Show Warning : turn on to show a warning in Edit Mode that reminds you to visit the page online to generate the Service Worker.Show Information : Show or hide important stack settings information.
PWA is Installable : turn ON to enable the website visitor to install the PWA on their desktop or device. Turn OFF to use the PWA for advanced caching only.Name : the name of your PWA.Short Name : this is the name of your PWA that is displayed under the icon on the users desktop or device.Description : type a description for your PWA.Display : select how the PWA will be displayed.
Options [ Full Screen, Standalone, Minimal UI, Browser ]
Start Page : set the PWA Start Page. This is the page that will be displayed when the user opens the PWA on their desktop or device.
Offline Page : set the PWA Offline Fallback Page. This is the page that will be displayed if the connection to the network is lost and the requested page has not yet been cached.
Show Console Messages : useful for troubleshooting, turn on to display all activity in the browser console.You should usually leave this turned off. - Theme Colors
Theme : set the Light and Dark Mode Theme Colors. This also sets the color of compatible browsers and will display dark or light depending on the users preference.Background : set the background color of your splash screen for Chrome. - Icon
512 x 512 PNG : add your PWA icon to the image well. Use a 512 x 512px PNG image. Other icon sizes will be created automatically. - Splash Screen
iPhone Image : add a splash screen to the image well. This will serve as the splash screen on iPhones. Use a 1284 x 2778 PNG image. Other sizes will be created automatically.iPad Image : add a splash screen to the image well. This will serve as the splash screen on iPads. Use a 2048 x 2732 PNG image. Other sizes will be created automatically. - Cache Settings (Documents)
Cache Documents : enable or disable advanced document caching.Cache Name : set a cache name for the documents.Cache Strategy : choose the cache strategy for documents.
Options: [ Stale While Revalidate (Default), Cache First, Network First, Network Only ]Max Entries : set the maximum number of documents that can be stored in the cache. When the maximum number is reached, documents requested the least will be deleted first.
Set 0 to disable this setting.Max Age : set the maximum age for documents stored in the cache. Once this age is reached, they are deleted from the cache.
Set 0 to disable this setting.Purge on Quota Error : Enable this to purge documents when the cache is full. - Cache Settings (Assets)
Cache Assets : enable or disable advanced asset caching. Assets are CSS & JavaScript.Cache Name : set a cache name for the assets.Cache Strategy : choose the cache strategy for assets.
Options: [ Stale While Revalidate (Default), Cache First, Network First, Network Only ]Max Entries : set the maximum number of assets that can be stored in the cache. When the maximum number is reached, assets requested the least will be deleted first.
Set 0 to disable this setting.Max Age : set the maximum age for assets stored in the cache. Once this age is reached, they are deleted from the cache.
Set 0 to disable this setting.Purge on Quota Error : Enable this to purge assets when the cache is full. - Cache Settings (Images)
Cache Images : enable or disable advanced image caching.Cache Name : set a cache name for the images.Cache Strategy : choose the cache strategy for images.
Options: [ Stale While Revalidate, Cache First (Default), Network First, Network Only ]Max Entries : set the maximum number of images that can be stored in the cache. When the maximum number is reached, assets requested the least will be deleted first.
Set 0 to disable this setting.Max Age : set the maximum age for assets stored in the cache. Once this age is reached, they are deleted from the cache.
Set 0 to disable this setting.Purge on Quota Error : Enable this to purge images when the cache is full. - Cache Settings (Fonts)
Cache Fonts : enable or disable advanced font caching.Cache Name : set a cache name for the fonts.Cache Strategy : choose the cache strategy for fonts.
Options: [ Stale While Revalidate, Cache First (Default), Network First, Network Only ]Max Entries : set the maximum number of fonts that can be stored in the cache. When the maximum number is reached, fonts requested the least will be deleted first.
Set 0 to disable this setting.Max Age : set the maximum age for fonts stored in the cache. Once this age is reached, they are deleted from the cache.
Set 0 to disable this setting.Purge on Quota Error : Enable this to purge fonts when the cache is full. - Cache Settings (Videos)
Cache Videos : enable or disable advanced video caching.Cache Name : set a cache name for videos.Cache Strategy : choose the cache strategy for videos.
Options: [ Stale While Revalidate, Cache First (Default), Network First, Network Only ]Max Entries : set the maximum number of videos that can be stored in the cache. When the maximum number is reached, videos requested the least will be deleted first.
Set 0 to disable this setting.Max Age : set the maximum age for videos stored in the cache. Once this age is reached, they are deleted from the cache.
Set 0 to disable this setting.Purge on Quota Error : Enable this to purge videos when the cache is full. - Cache Settings (Audio)
Cache Audio : enable or disable advanced audio caching.Cache Name : set a cache name for audio.Cache Strategy : choose the cache strategy for audio.
Options: [ Stale While Revalidate, Cache First (Default), Network First, Network Only ]Max Entries : set the maximum number of audio files that can be stored in the cache. When the maximum number is reached, audio files requested the least will be deleted first.
Set 0 to disable this setting.Max Age : set the maximum age for audio files stored in the cache. Once this age is reached, they are deleted from the cache.
Set 0 to disable this setting.Purge on Quota Error : Enable this to purge videos when the cache is full. - Cache Settings (Google Fonts)
Cache Google Fonts : enable or disable advanced Google Font caching.Cache Name : set a cache name for the Google Font Stylesheets.Cache Strategy : choose the cache strategy for the Google Font Stylesheets.
Options: [ Stale While Revalidate (Default), Cache First, Network First, Network Only ]Max Entries : set the maximum number of Google Font Stylesheets that can be stored in the cache. When the maximum number is reached, the Google Font Stylesheets that are requested the least will be deleted first.
Set 0 to disable this setting.Max Age : set the maximum age for the Google Font Stylesheets stored in the cache. Once this age is reached, they are deleted from the cache.
Set 0 to disable this setting.Purge on Quota Error : Enable this to purge Google Font Stylesheets when the cache is full.
Cache Name : set a cache name for the Google Web Fonts.Cache Strategy : choose the cache strategy for the Google Web Fonts.
Options: [ Stale While Revalidate, Cache First (Default), Network First, Network Only ]Max Entries : set the maximum number of Google Web Fonts that can be stored in the cache. When the maximum number is reached, the Google Web Fonts that are requested the least will be deleted first.
Set 0 to disable this setting.Max Age : set the maximum age for the Google Web Fonts stored in the cache. Once this age is reached, they are deleted from the cache.
Set 0 to disable this setting.Purge on Quota Error : Enable this to purge Google Web Fonts when the cache is full. - Mode
Mode : you should only change this setting if you are using more than one PWA on your site.
Options: [ Normal (Default), Admin, Custom ]Custom : set a custom identifier for this PWA. It should be a short, single word, with no spaces and be unique. - Advanced
Precache Additional URLs : enable the Pre-Cache URLs Child Stack.Define Custom Strategies : enable the Custom Cache Strategies Child Stack.
- Precache Asset
Asset URL : set the URL of a local or remote resource to add to the pre-cache.Asset Revision : set the cached asset revision, or leave on Auto (recommended).
- Strategy Settings
Path Prefix : choose the path prefix for this custom cache strategy.
Options: [ Starts With (Default), Ends With ]Path : set the path for this custom cache strategy. The path must be the actual path from the document root. If you are unsure of the correct path to use, check the name in Google Chrome -> Application -> Cache Storage.Request Type : choose the network request type.
Options: [ All Types, Documents, Assets (JS & CSS), Images, Fonts, Audio, Video ]Cache Strategy : choose the custom cache strategy for this path.
Options: [ Stale While Revalidate (Default), Cache First, Network First, Network Only ]Max Entries : set the maximum number of entries that can be stored in the cache. When the maximum number is reached, the entries that are requested the least will be deleted first.
Set 0 to disable this setting.Max Age : set the maximum age for the entries stored in the cache. Once this age is reached, they are deleted from the cache.
Set 0 to disable this setting.Purge on Quota Error : Enable this to purge these entries when the cache is full.
- Settings
PWA Stack : set the page where your PWA Stack is installed.
Show Console Messages : useful for troubleshooting, turn on to display all activity in the browser console.You should usually leave this turned off. - Mode Mode : this should match the mode that is set in the PWA stack. You should only change this setting if you are using more than one PWA on your site.
Options: [ Normal (Default), Admin, Custom ]Custom : set a custom identifier for this PWA. It should be a short, single word, with no spaces and be unique.
- Mode Mode : this should match the mode that is set in the PWA stack. You should only change this setting if you are using more than one PWA on your site. If you are using more than one PWA, but only one Offline Page, the mode only needs to match one of your PWAs.
Options: [ Normal (Default), Admin, Custom ]Custom : set a custom identifier for this PWA. It should be a short, single word, with no spaces and be unique.
- Edit Mode
Preview Message : show or hide the Add to Home Screen message in Edit Mode. - Settings
Start Delay : set the delay, in seconds, before the Add to Home Screen message appears on the page.Lifespan : set the time, in seconds, that the Add to Home Screen message stays visible on the page.Display Interval : set the time, in minutes, before the Add to Home Screen message is shown again. The default is 1440 minutes (1 day). Set at 0 to display every time the page is visited.Display Count : set the maximum number of times to display the Add to Home Screen message. Set at 0 to disable this setting.Skip First Visit : turn on to hide the Add to Home Screen message on the first visit to the site. This is useful if the display count is 1, but you use a cookie consent modal that refreshes the page when cookie consent is set.Modal Mode : turn on to disable the page until the Add to Home Screen messages has been closed. - Local Storage
Name : set the name of the string that is saved to the Browser Local Storage to store the Add to Home Screen status. - Style
Text Size : set the size of the Add to Home Screen message text.Text Color : set the color of the Add to Home Screen message text.Background : set the background color of the Add to Home Screen message.Rounding : set the rounding of the Add to Home Screen message.
- Firebase - General
API Key : paste the API Key from your Firebase App Settings.Auth Domain : paste the Auth Domain from your Firebase App Settings.Project ID : paste the Project ID from your Firebase App Settings.Storage Bucket : paste the Storage Bucket from your Firebase App Settings.Sender ID : paste the Sender ID from your Firebase App Settings.App ID : paste the App ID from your Firebase App Settings. - Firebase - Cloud Messaging
Certificate Key : paste the Certificate Key from your Firebase App - Cloud Messaging settings.
