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 # required
    - icon-512x512.png # required
    #- src: icon-192x192-maskable.png
    #  purpose: maskable
    #- src: icon-512x512-maskable.png
    #  purpose: maskable

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:
      enabled: true
  offline:
    snackbar:
      enabled: true

Define ignored paths:

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

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

---
serviceworker:
  precache: false
---