README

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 assets and published pages
• Offline support and image placeholder
• Custom install button support instead of browser prompt

Prerequisites

• A Cecil website
• A supported browser
• HTTPS

Installation

composer require cecil/theme-pwa

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

Usage

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

theme:
  - pwa

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

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

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 theme_color_dark option.
The icons section is optional. If not provided, the theme will generate a default set of icons based on the icon.png file in the assets directory of your website.

Tip

Create your own maskable icons with Maskable.app.

Web manifest Optional

Add shortcuts from the main menu entries:

manifest:
  shortcuts: true

Provide installer screenshots:

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

Service worker

Enable the service worker:

serviceworker:
  enabled: true

Service worker Optional

Disable browser install prompt, and use custom install button:

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

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

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 list of precached assets:

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

Display a snackbar on update and connection lost:

serviceworker:
  update:
    snackbar: true
  offline:
    snackbar: true

Define ignored paths:

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

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

---
serviceworker:
  precache: false
---