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

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
---

cecil / theme-pwa

Maintainers

Details