How-to
Website
Web app
Make a site work offline
Keep a site working when the network is gone: the build writes a service worker, sw.js, that stores the site's pages on the reader's device, and a page that was not stored shows a fallback page of your own. Before you start: - Serve the site over HTTPS, or from localhost. Browsers run service workers only from a secure origin. - Serve sw.js fresh. The page registers the worker with updateViaCache: "none", so the browser asks for it on every visit — but a CDN in front can still hold a copy. Give sw.js the header Cache-Control: no-cache (Cache and security headers). - Deploy everything in build/ together. The worker's version is a hash of every file the build wrote, so deploying half a build confuses it. Add offline to webfluent.app.json:
Needs: the offline setting below, a site served over HTTPS (or from localhost), and a page at / for the fallback page to link to.
{ "offline": {
"precache": ["/", "/docs/*"],
"fallback": "/offline",
"cache": { "/api/*": "network-first" },
"sync": true
} }
The fallback is an ordinary page of your site. This one tells the reader what happened:
page Offline(path: "/offline", title: "Offline", description: "Shown when a page was not stored.") {
Heading("You are offline").h1
Text("This page was not saved for offline use. It will load when you are back online.")
Link("Go to the home page", to: "/")
}
How it works
With offline in the config, the build writes sw.js beside the pages. Each key says what it keeps and how:
| Key | What it does |
|---|---|
|
|
The routes a first visit stores, as globs. |
|
|
A page's |
|
|
How a path the build did not write — an API, say — is fetched: |
|
|
Keep a write that is safe to send twice — a |
A stored route loads with no network at all. When there is a network, a navigation still goes to it first, so a page that changed is never served stale while the server is there to ask.
What the worker keeps
What a cache entry fetches is kept in the worker's runtime store, the 200 most recently fetched answers, for the next reader of the device — so an answer that is one reader's is never kept: one the server marks Cache-Control: no-store or private, one asked for with an Authorization header, and one that varies by Cookie or Authorization. Mark what is personal private and it stays off the device.
Two sites on one origin under different base_paths keep apart: each has its own stores, kept writes and persist values (wf:/shop:cart), and neither deletes, serves or sends the other's. A site at the root keeps the names it always had, and one under a base path reads a value kept under the old name once and keeps it under the new one.
Note
Under wf serve the worker removes itself. A page answered from its own store would hide every edit you make.
Test it offline
Because wf serve removes the worker on purpose, test the built output with a plain static server. Build the site and serve build/:
$ wf build
$ python3 -m http.server -d build
Then, in the browser:
- Open the site. In the developer tools, open Application → Service workers and check the worker is activated.
- In the Network panel, tick Offline and reload. Stored routes load; every other route shows the
fallbackpage. - Make a
PUTor aDELETEwhile offline: its call fails as.offline(queued: true), andnetwork.queuedcounts it. Untick Offline. The write goes out, andnetwork.queueddrops to zero.
wf verify runs against the built output too, and the repository's own browser tests hold the whole flow to a real Chrome.
Troubleshooting
- A
POSTor aPATCHmade offline is not sent later. Only a write that is safe to send twice is kept: aPUT, aDELETE, or an endpoint markedidempotent. Any other write fails as.offline(queued: false), and the page says so; one whose answer was lost may have reached the server, and sent again it would be a second order. - An upload made offline fails. A
Filebody is never kept: the call fails as it would withoutsync. Ask the reader to try again online. - A write arrives at the server minutes late. That is the design: a kept write is sent once it can be. Make the server's endpoints safe to receive late, and idempotent where a retry could repeat one.
- The API the site needs does not work offline. What
cachedoes not name passes straight through to the network. Give the API anetwork-firstorstale-while-revalidateentry. - A page that loaded offline yesterday has to be fetched again. The browser decides how much it keeps, and can evict the store under storage pressure. The next visit with a network stores it again.
- Readers keep getting the old version. Something in front of the site caches
sw.js. Serve it withCache-Control: no-cache. - Nothing is stored when you test with
wf serve. The dev server removes the worker. Test the output ofwf buildwith a static server.