cecil/theme-pwa

Cecil component theme PWA

2.11.0 2024-12-22 00:39 UTC

Requires

• cecil/theme-installer: ^1.4||^2.0

MIT

• theme
• pwa
• service worker
• cecil

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 published pages
• Precaching of a list of assets
• Generic offline page and default image (SVG)

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

Web manifest

Add the web manifest in the HTML <header> of the main template:

<link rel="manifest" href="{{ url('manifest') }}">

Configure it:

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

Tip

Create your own maskable icons with Maskable.app.

Web manifest Optional

Add shortcuts:

manifest:
  shortcuts: true

Add installer screenshots:

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

Service worker

Register the service worker before the end of the HTML </body> of the main template:

{{ include('partials/regsw.js.twig', {site: site}, with_context = false) }}

Enable the service worker:

serviceworker:
  enabled: true

Service worker Optional

Disable browser install prompt:

serviceworker:
  install:
    prompt: false

Set list of precached assets:

serviceworker:
  install:
    precache:
      assets:
        - logo.png
        - icon-192x192.png
        - icon-512x512.png
        - icon-192x192-maskable.png
        - icon-512x512-maskable.png

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

serviceworker:
  install:
    precache:
      pages:
        limit: 10

Display a snackbar on update:

serviceworker:
  update:
    snackbar:
      enabled: true

Display a snackbar if connection lost:

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