PWA Usage - js-lib-com/wood GitHub Wiki

In order to convert a classic web application into PWA - Progressive Web Application - one needs to:

• create icons with various sizes,
• create PWA manifest file,
• create PWA service loader script,
• create PWA service worker script.

It seems mandatory to have application icon with multiple size variants. Here are recommended sizes: 128, 144, 152, 192, 256. WOOD tools have a command that can help.

Application icons are declared into manifest file. WOOD tools read icons property from manifest file and create all necessary sizes.

See manifest icons for details.

Manifest file is a JSON file providing information about a web application, necessary for the web app to be downloaded and used similarly to a native app.

Default file location is manifest.json but can be configured in project descriptor.

• project.xml

<project>
	<pwa-manifest>asset/manifest.json</pwa-manifest>
</project>

Here is a minimal but working manifest file that can be used as template on new projects. Beside application icons, there are couple options a developer may want to customize. See manifest description.

• manifest.json

{
    "name": "@project/title",
    "icons": [
        {
            "src": "@image/app-icon-96",
            "sizes": "96x96",
            "type": "image/png"
        },
        {
            "src": "@image/app-icon-128",
            "sizes": "128x128",
            "type": "image/png"
        },
        {
            "src": "@image/app-icon-144",
            "sizes": "144x144",
            "type": "image/png"
        },
        {
            "src": "@image/app-icon-152",
            "sizes": "152x152",
            "type": "image/png"
        },
        {
            "src": "@image/app-icon-192",
            "sizes": "192x192",
            "type": "image/png"
        },
        {
            "src": "@image/app-icon-256",
            "sizes": "256x256",
            "type": "image/png"
        }
    ],
    "start_url": "@layout/page/index",
    "display": "fullscreen",
    "background_color": "white",
    "theme_color": "white"
}

Update start_url property if home component page is not page/index.

Service loader script takes care to register PWA service worker. WOOD tools embeds loader script into every generated page.

Default file location is loader.js but can be configured in project descriptor.

• project.xml

<project>
	<pwa-loader>script/loader.js</pwa-loader>
</project>

This script file does not require customization.

• loader.js

if ("serviceWorker" in navigator) {
    navigator.serviceWorker
        .register("@project/pwa-worker")
        .then(registration => console.log("Service worker registration succeeded: ", registration))
        .catch(error => console.log("Service worker registration failed: ", error));
} else {
    console.log("Service workers are not supported.");
}

Service worker is primarily a proxy used to managed offline experience. Sample file provides the skeleton but only minimal support for caching.

Default file location is worker.js but can be configured in project descriptor.

• project.xml

<project>
	<pwa-worker>script/worker.js</pwa-worker>
</project>

For service worker developer needs to update and keep in sync the list of files to cache.

• worker.js

var cacheName = "@project/title";
var filesToCache = [
    "@layout/page/index"
];

self.addEventListener("install", event => {
	event.waitUntil(caches.open(cacheName).then(cache => {
        cache.addAll(filesToCache);
    }))
});

self.addEventListener("fetch", event => {
	event.respondWith(caches.match(event.request).then(response => response || fetch(event.request)))
});

See service worker API.

Last updated 9/8/2022.