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 say | Technique | What happens |
|---|---|---|
| keep nothing but the site's own static files | allow list | kindOf() 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 response | response rule | cacheableResponse() refuses a failed, cross-origin or opaque response and any Cache-Control with no-store or private. |
| not ours is not answered | pass | strategy() gives 'pass', and the handler returns without respondWith, so the request goes to the network untouched. |
| network first for a page | strategy | answerPage() fetches, keeps a clone, and on failure answers from the cache, then the offline page. |
| the offline page in the visitor's language | folder map | offlinePageFor() takes the first path segment after the scope and looks it up with Object.hasOwn, falling back to the default. |
| one classic script | build | swSource() joins offline.core.js (exports removed), the settings as CONFIG, and sw.template.js. |
| the first visit is enough | message | registerOffline() posts { type: 'keep', urls } from resource timing after load and idle; the worker re-checks each URL. |
| old copies thrown away | version | cacheName(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 request | Answer |
|---|---|
| a page, online | the network's, and a copy kept |
| a page, offline | the copy kept on the last visit; else the offline page in the language of the page asked for |
| a file the page needs | the kept copy first; the network fills the cache the first time |
a POST, another address, a data file, a response marked no-store or private | not 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.jsandexport/png.jsthen) is not in the new cache until it has been used online once, so offline it would fail after an update. List such files inprecache; the template does. - The version is a hash that only
pages.mjscomputes. The event template's worker version is a content hash of every file the worker keeps, written bynode 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 --checkcatches the forgotten run: it fails whensw.jsis 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
loadnever firing; the requests still in flight were the lazyskins/quiet.jsofqr,person-cardandsite-footer, and onceGET /. 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 responseno-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, runtools/until-fail.mjson 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 sendsno-storeonsw.js, and whatnavigator.serviceWorker.getRegistration()says (installing, waiting or active) while it lasts. A worker script servedCache-Control: no-storestalls 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.