PWA component theme

The PWA component theme for Cecil provides helpers to implement a Web manifest and a service worker to turn a website into a Progressive Web App.

Features

• Generated and configurable Web manifest
• Generated and configurable service worker
• Automatic caching of visited resources
• No dependencies, vanilla JavaScript
• Precaching of icons, assets and published pages
• Offline support: fallback page and image placeholder
• Custom install button support instead of browser prompt
• Update notifications: snackbar, app badge and system notification
• Menu entries as app shortcuts
• Translatable messages (English and French included)

Prerequisites

• A Cecil website
• A supported browser
• HTTPS (or localhost during development)

Installation

composer require cecil/theme-pwa

Or download the latest archive and uncompress its contents in themes/pwa.

Usage

Add pwa in the theme section of the config.yml:

theme:
  - pwa

Add the following line in the HTML <head> of the main template:

{{ include('partials/pwa.html.twig', {site}, with_context = false) }}

This partial adds the theme-color meta tag(s), the link to the Web manifest and the service worker registration script.

The theme generates the following files:

File	Description
/manifest.webmanifest	Web manifest
/serviceworker.js	Service worker
/offline.html	Fallback page displayed when offline

Web manifest

Configure Web manifest options:

manifest:
  background_color: '#FFFFFF'
  theme_color: '#202020'
  icons:
    - icon-192x192.png
    - icon-512x512.png
    - src: icon-192x192-maskable.png
      purpose: maskable
    - src: icon-512x512-maskable.png
      purpose: maskable

Note

You can specify a dark theme color with the theme_color_dark option.
The icons section is optional. If not provided, the theme generates a default set of icons (192 and 512 pixels, standard and maskable) from the icon.png file of the assets directory of your website.

Tip

Create your own maskable icons with Maskable.app.

The following options are also available, with their default values:

manifest:
  name: <site.title>
  short_name: <site.title> # truncated to 12 characters
  description: <site.description>
  display: standalone
  display_override: standalone
  start_url: <home page URL>
  id: <home page URL>
  orientation: any
  dir: ltr

Optional Web manifest settings

Add shortcuts from the main menu entries (external links are ignored):

manifest:
  shortcuts: true

Tip

Shortcuts use the icon-link.png icon: add your own file with this name in the assets directory to override it.

Provide installer screenshots (relative to the assets directory):

manifest:
  screenshots:
    - screenshots/desktop.png
    - screenshots/mobile.png

Note

The form_factor is automatically set to narrow (portrait image) or wide (landscape image).

Service worker

Enable the service worker:

serviceworker:
  enabled: true

Important

The service worker is registered with the / scope.
If the service worker is disabled afterwards (enabled: false), it is automatically unregistered from the visitors browsers and their caches are deleted.

Optional service worker settings

Disable the browser install prompt and use a custom install button:

serviceworker:
  install:
    prompt: false
    button: '#install-button' # query selector

<button id="install-button" hidden>Install App</button>

Note

The button must be hidden by default: it is displayed only when the browser allows the installation, and hidden again once the app is installed.

Icons defined in manifest.icons are precached by default. To disable this behavior:

serviceworker:
  install:
    precache:
      icons: false

By default, all published pages are precached. To limit this number:

serviceworker:
  install:
    precache:
      pages:
        limit: 10

Set the list of precached assets (relative to the assets directory):

serviceworker:
  install:
    precache:
      assets:
        - logo.png

Do not precache a specific page (through its front matter):

---
serviceworker:
  precache: false
---

Define ignored paths (requests starting with these paths are never cached):

serviceworker:
  ignore:
    - name: 'cms'
      path: '/admin'

Set the cache mode of requests stored by the service worker (reload by default, or default):

serviceworker:
  cache:
    request: default

Notify the user when a new version of the website is available, through a snackbar, a badge on the app icon and/or a system notification:

serviceworker:
  update:
    snackbar: true
    badge: true
    notification: true

Note

Enabling notification asks the user for permission to display notifications.

Display a snackbar on connection loss:

serviceworker:
  offline:
    snackbar: true

Use a custom offline page, by its ID (offline by default):

serviceworker:
  offline:
    page: my-offline-page

Tip

On a multilingual website, the offline page of the current language is used.

Debug

When debug: true is set in the site configuration, the service worker logs its activity (installation, precaching, cache hits, etc.) in the browser console.

Translations

Messages (snackbar, notification and offline page) are translatable. A French translation is included; add your own in the translations directory of your website (e.g.: messages.de.yml).

License

The PWA component theme is a free software distributed under the terms of the MIT license.