Susegad UI Accessibility GitHub

How this site looks

The view settings need JavaScript. Every page reads well without them.

Mood

The same pages, in three moods.

Theme

Recipes

Offline

A small service worker for a static site and the page that registers it, so after one visit the site's pages open again with no connection and a page never opened shows a kind 'no connection' page in the visitor's language.

quiet warm playful

Open the live demo npx @susegad/cli add offline

Stands on: Core: strings by language, Tokens

The prompt

the prompt

After one visit, the site's pages open with no connection, and a page never opened shows a kind "no connection" page.

A small service worker that keeps the site's own pages and the files they need, and nothing else.

import { writeSw } from './susegad/recipes/offline/build.mjs';
writeSw('sw.js', { version: '1', scope: '/', offlinePages: { '': 'offline.html', 'gom-deva': 'gom-deva/offline.html' }, precache: ['site.css'] });
<script type="module">
  import { registerOffline } from './susegad/recipes/offline/offline.js';
  registerOffline({ url: 'sw.js', scope: '/' });
</script>

The prompt

Write a small service worker for a static event site and the page script that registers it. The worker is one classic script (module workers are not in every browser) made by a Node build function from a pure, tested file of rules plus the site's settings (a version, a scope that starts and ends with a slash, an offline page per language folder with a default, and a few files to keep at install). It keeps only the site's own pages and the files they need: pages (a folder or .html), styles and scripts, fonts, pictures. It keeps a file only when the request is a GET, to its own address, inside its scope, of one of those kinds, and when the response worked, came from its own address and does not say no-store or private. Everything else (a POST, another address, a data file, an API path) it does not answer at all, so it goes to the network as if there were no worker. Answer a page with the network first, then the copy kept, then the offline page in the language of the page that was asked for; answer a file the page needs from the copy first, and let the network fill the cache. Key every copy by address with no query or hash. On install keep the offline pages; on activate delete every cache that starts with the recipe's prefix and is not the current version, and take over open pages. A worker installed during a first visit did not see that visit's requests, so after load and idle the page registers the worker and posts it the list of files it used (from the resource timing entries, filtered by the same rules, deduplicated and capped); the worker checks the list again before keeping anything. The page script never throws: no service worker, a refusal or a failed install leave the page as it was. No personal data is ever kept: a visitor's ticket lives in localStorage and is drawn by script, never cached. Test the rules in Node, test the generated worker in a fake scope with a cache and a network that can be cut, and test in a real browser, after a first visit, with the network cut.

Words to code

When you sayTechniqueWhat happens
keep nothing but the site's own static filesallow listkindOf() allows only page, style, script, font and picture extensions; isCacheable() adds GET, same origin and inside the scope. Unit-tested against POSTs, other addresses, .json and /api/.
never keep a private responseresponse rulecacheableResponse() refuses a failed, cross-origin or opaque response and any Cache-Control with no-store or private.
not ours is not answeredpassstrategy() gives 'pass', and the handler returns without respondWith, so the request goes to the network untouched.
network first for a pagestrategyanswerPage() fetches, keeps a clone, and on failure answers from the cache, then the offline page.
the offline page in the visitor's languagefolder mapofflinePageFor() takes the first path segment after the scope and looks it up with Object.hasOwn, falling back to the default.
one classic scriptbuildswSource() joins offline.core.js (exports removed), the settings as CONFIG, and sw.template.js.
the first visit is enoughmessageregisterOffline() posts { type: 'keep', urls } from resource timing after load and idle; the worker re-checks each URL.
old copies thrown awayversioncacheName(version) and the activate handler delete other caches with the prefix.

A small service worker for a static site, and the page that registers it. After a visitor has opened the site once, its pages open again with no connection, in their own language, and a page that was never opened shows a kind "no connection" page instead of the browser's own. It keeps the site's own pages and the files they need (styles, scripts, fonts, pictures) and nothing else. What it may keep, and what it never will, is decided in docs/decisions/0028-offline-cache.md: no response to a form or an API, nothing from another address, and no personal data. A visitor's ticket is not in the cache; it is made on their device and drawn by script from the device's own storage.

Make the worker

The worker is one classic script, made from offline.core.js and your settings, so it is tested in Node and still runs in every browser:

// in your build script, in the folder the site is served from
import { writeSw } from './susegad/recipes/offline/build.mjs';

writeSw('sw.js', {
  version: '1',                        // change it when the files kept change; old copies are thrown away
  scope: '/',                          // the folder the worker covers: starts and ends with a slash
  offlinePages: {                      // folder name -> its offline page; "" is the default
    '': 'offline.html',
    'gom-deva': 'gom-deva/offline.html',
    'gom-latn': 'gom-latn/offline.html',
  },
  precache: ['site.css', 'look.js'],   // kept at install, besides the offline pages: what an offline page needs to draw
});

The event template does this in pages.mjs; run node pages.mjs and sw.js is written beside the pages.

Register it

<script type="module">
  import { registerOffline } from './susegad/recipes/offline/offline.js';
  registerOffline({ url: 'sw.js', scope: '/' });
</script>

registerOffline() waits until the page has loaded and the browser is idle, registers the worker, and tells it which files the page used so that the first visit is enough (a worker installed during that visit did not see the page's own requests). It never breaks a page: no service worker in the browser, a refusal, a failed install each leave the page as it was. It returns { registered, kept, why } for a page that wants to say something.

An offline page is an ordinary page of your own. The event template's three (offline.html, gom-deva/offline.html, gom-latn/offline.html) use words that say the fault is not the visitor's, what still works, what has to wait, and offers Try again and Back.

What it does

A requestAnswer
a page, onlinethe network's, and a copy kept
a page, offlinethe copy kept on the last visit; else the offline page in the language of the page asked for
a file the page needsthe kept copy first; the network fills the cache the first time
a POST, another address, a data file, a response marked no-store or privatenot answered and not kept: it goes to the network as if no worker were there

The offline page promises only what the worker keeps. If you change what is kept, change the words on that page to match.

Test it

node --test packages/recipes/offline/offline.test.js runs the generated worker in a fake scope (a cache that remembers and a network that can be cut): install, activate, a page kept and answered with the network cut, the offline page in each language, a file answered from the cache, and every request that must not be answered or kept. node packages/recipes/offline/offline.check.mjs does the same in a real browser with the network cut (Chromium and WebKit).

Serving it

Serve sw.js and the files it keeps with ordinary static-file headers (Cache-Control: public, max-age=0, must-revalidate or a short max-age). A response marked no-store or private is never kept, by design, so a host that sends no-store on every file (the repo's own dev server does) leaves the worker with nothing to keep; and in Chromium a worker script served no-store stalled its own fetches during install (found 8 October 2026). The recipe's browser check therefore uses a small static server that sends what a real host sends.

Known issues

  • A new version starts with an empty cache. When the worker's version changes it deletes the old copies, and the new version keeps only what it is told to at install and what the page then loads. A file the page loads only when something is pressed (the event template's Save as picture loads ticket.png.js and export/png.js then) is not in the new cache until it has been used online once, so offline it would fail after an update. List such files in precache; the template does.
  • The version is a hash that only pages.mjs computes. The event template's worker version is a content hash of every file the worker keeps, written by node pages.mjs. Edit a kept file (a style, a script, a page) without running it again and the worker's version does not change, so returning visitors keep the old file. node pages.mjs --check catches the forgotten run: it fails when sw.js is not what the files make.
  • A stall of 20 to 30 seconds in Chromium after a version bump is real, and its cause is not found. Reproduced by a reviewer on the real event template on 8 October 2026: 2 of 2 bump-and-reload sequences in the second review and 4 of 5 across both. The third reload sat for 30 s with load never firing; the requests still in flight were the lazy skins/quiet.js of qr, person-card and site-footer, and once GET /. WebKit had no stall in 4 reloads, and the ticket was intact. It is not ruled out that the single-threaded test server and a loaded machine caused it. It did not appear in a small script of this recipe's own (12 rounds, 60 navigations on a mini-site, slowest 1.1 s; and 3 rounds with every response no-store, slowest 0.7 s), so it needs the real page's load of many lazily imported files at the moment the new worker installs. Before the first live site, run tools/until-fail.mjs on the bump-and-reload sequence (first visit, change a kept file, rebuild, reload three times) against a real host, and record what it shows. Something to note if it stalls: whether the host sends no-store on sw.js, and what navigator.serviceWorker.getRegistration() says (installing, waiting or active) while it lasts. A worker script served Cache-Control: no-store stalls its own install-time fetches for good (see "Serving it"), which would show as a worker that never takes over rather than a slow page.

Where the ticket comes in

The ticket is the sg-ticket component. It is made on the visitor's device, kept in localStorage, and drawn into the event page by script. Offline, the cached page loads, finds the ticket in localStorage and draws it, so the ticket opens with no connection although no copy of it was ever cached.

Not here

Background sync, push, periodic updates and keeping a ticket across devices (decision 0028). A service worker anywhere outside this recipe needs a decision of its own.