Loading

The Service Worker Engine

A service worker is a small piece of code the browser keeps running for your site. It is what makes offline caching and push notifications possible.

Where to find it

Architect Panel → Configuration:

  • Site Settings — the Progressive Web App and Service Workers option groups

Architect Panel → Layout & Pages:

  • Dependencies — the files the site loads, and what the offline cache is built from

Architect Panel → Background Messaging:

  • Push Notifications — the VAPID keys web push needs

The switches

  • Enable Service Worker Engine — the master switch. Off, none of the rest applies and the service worker is not served at all.
  • Enable Offline Cache Engine — caching of pages and resources.
  • Enable Push Notification Engine — web push.

Then three scope switches decide where the offline cache applies:

  • Main website
  • Web app
  • Admin panel

The scopes are separate for a reason

Each gets its own service worker with its own file list. So you can cache the web app aggressively — where the audience is known and the content is stable — while leaving the administration panel uncached, where staleness would be confusing and the audience is small.

Start with the web app scope only

It is the scope with the clearest benefit and the smallest blast radius. Prove it works there before extending to the main website, and think hard before enabling it on the admin panel.

Caching the admin panel is rarely worth it

Administrators are usually on good connections at a desk, and a cached administration interface showing yesterday’s assets while somebody debugs a problem is actively harmful.

Service workers are sticky

The most important operational fact. Once installed in somebody’s browser, a service worker persists — it survives page reloads and keeps serving cached content.

So a mistake in what you cache reaches users and stays with them, and it is not fixed by you correcting the configuration alone.

They need HTTPS

Service workers do not run over plain HTTP. That is a browser rule and there is no way round it.

Test in a private window

Because your own browser will have an old service worker and an old cache, and you will spend an afternoon debugging something that was fixed twenty minutes ago. A fresh private window has neither.

Know how to clear one

Before you enable anything. In the browser’s developer tools, under Application, a service worker can be unregistered and its caches cleared. That is the answer to almost every strange caching problem, and it is what you will be talking a user through.

Worked example

An organisation enabled the engine with offline caching on the web app scope only, tested in private windows, and wrote a two-line support note on unregistering the service worker. The main website scope was added a month later; the admin panel was left off deliberately.

Recommendations

  • Web app scope first, alone.
  • Leave the admin panel uncached.
  • Test in private windows, always.
  • Write the "unregister it" note before you need it.