Shipping a Kotlin Compose Multiplatform app as a PWA: getting updates and caching right

The PWA packaging described here is handled by the ComposePWA Gradle plugin (dev.yuyuyuyuyu.composepwa) — github.com/yuyuyuyuyu-dev/ComposePWA. Under the hood it uses Google’s Workbox to generate the service worker from a small config file — the examples below assume it lives at webApp/workbox-config-for-wasm.js.

All paths in the examples that follow assume a default Kotlin Multiplatform / Compose Multiplatform (CMP) project structure, as produced by any of the usual project setup wizards; adjust them if your module layout differs.

That detail matters for everything below: when the rest of this post talks about "the Workbox config" or "the generated `serviceWorker.js`", that’s the file the ComposePWA plugin produces via Workbox. Knowing where the worker comes from is what makes the configuration choices make sense.

A common starting point is a Workbox config that precaches nothing and instead routes everything through a StaleWhileRevalidate strategy:

This produces a frustrating "two launch" lag after every deploy, for two compounding reasons:

Tell Workbox to precache the build output. This embeds a per-file revision manifest into serviceWorker.js, so the worker’s bytes change on every deploy, the browser detects a new worker, and the update flow runs.

Pair it with a registration script that checks for updates and reloads once the new worker takes control:

Now a returning user runs the new software on the first relaunch: registration.update() fetches the new (byte-changed) worker → it precaches the new assets → skipWaiting activates it → clientsClaim takes control → controllerchange fires → the guarded reload swaps the page to the new version.

The step above catches updates at page load. But a Compose Multiplatform app is often left open for a long time — more like a desktop app than a page you navigate away from. To let a running instance notice a new deploy, poll for updates while the tab is alive:

With skipWaiting + clientsClaim still in place, a new build found by the poll activates and reloads the open tab on its own — no manual relaunch.

Polling is worthless if the browser answers the poll out of its own HTTP cache, and that is the default outcome on a plain static host.

registration.update() re-fetches serviceWorker.js through the ordinary HTTP cache. If the server sends Last-Modified and ETag but no Cache-Control — which is exactly what a stock Apache or nginx does — the browser falls back to heuristic freshness, conventionally about 10% of the resource’s age. The update check is then served from cache without touching the network at all, and your deploy goes unnoticed.

The result is a poll that only looks like it works: you check every few minutes, but detection lags by an interval that grows with how long ago you last deployed (the service-worker spec caps it at 24 hours). Everything else in this post can be correct and the update will still arrive late.

Tell the browser to always revalidate. For a static PWA host, applying this to the whole deployment is the simplest thing that is correct:

Despite the name, no-cache does not disable caching — it means "you may store this, but you must revalidate before reusing it". That is precisely what you want from the file whose entire job is to signal "something changed", and the cost is nothing: a revalidation that finds no change is a 304 with an empty body.

The obvious-looking stronger option is a trap worth naming, because "disable caching" is what most snippets on the web will hand you:

no-store says "never write this down at all". It is equally correct — you will never serve a stale version — but the browser now holds no validators, so it has nothing to send an If-None-Match with. Every check becomes a full download instead of a 304. You have paid bandwidth for a guarantee no-cache already gave you.

must-revalidate is redundant alongside no-cache (it governs what happens once a response goes stale, and under no-cache a response is never reusable without checking first). Companion Pragma: no-cache and Expires: 0 headers are HTTP/1.0-era fallbacks — harmless, but no browser you are targeting needs them.

The one real reason to reach for no-store is privacy: keeping sensitive responses off disk. Static app assets and public data are not that.

Everything in Part 1 assumes the browser will load your new index.html. If a previous build of your app already registered a hand-written service worker — the usual first attempt, precaching the shell and serving it cache-first — that assumption fails for exactly the users you most need to reach:

Deploying the new version does nothing for those clients. They are not choosing the old build; they never learn a new one exists. No amount of code in the new build can reach them, because the new build is never fetched.

The one channel that still works is the old worker’s own update check: the browser periodically re-fetches the URL the old worker was registered from, and that request goes through the ordinary HTTP path rather than the worker’s cache. So serve a tombstone there — a valid script, at the old worker’s exact filename, whose only job is to switch its predecessor off:

Deleting the old file instead (letting it 404) also clears the registration in Chrome eventually, via a failed update check — but it is browser-dependent, undated, and it leaves the old multi-megabyte precache on the device forever.

The tombstone is a deployment obligation with a lifetime, not a file you land and forget: it must stay at that URL until you are confident the last stale client has come back. Pick that date from how long a user might plausibly stay away — for an app tied to a yearly event, comfortably more than a year — and write the reasoning into the file header, because nothing else will remind you. Delete it early and you strand precisely the users it existed for. There is no telemetry for "the last old client returned"; when in doubt, keep it. It costs kilobytes.

If the app manages its own data cache — which it should, because that’s the abstraction that already works on every other platform — then the service worker should cache only the software and touch nothing else. Concretely: remove runtimeCaching entirely.

With no matching route, Workbox’s fetch handler simply doesn’t call respondWith() for a data request, so the browser handles it as a normal network fetch. The worker still sees the request (a negligible routing check) but neither answers nor caches it. Your data layer is back in sole control — exactly as it is on desktop and mobile.

On the app side, data lives behind a small Store abstraction backed by the browser’s Cache API. It is tempting to reach for localStorage instead — it’s synchronous and takes one line — but for anything beyond a scratch value it is the wrong tool: a few megabytes of quota, strings only, and it blocks the main thread. The Cache API is the one built for this job, and it stores a body plus its headers, which turns out to matter more than it sounds.

Every operation is suspend — the Cache API is promise-based, and file I/O on the desktop target shouldn’t run on the UI thread either.

Two details are worth calling out, because both bite people:

Because the entry keeps the server’s real Last-Modified header, revalidating it with a conditional GET needs no bookkeeping of our own — you read the header back out of the cache and send it straight up as If-Modified-Since:

Had the entry been a JSON blob in localStorage, that lastModified field would have to be invented, serialized and kept in sync by hand. Storing a real response with real headers means the revalidation metadata simply is the cache entry.

The per-platform actual for Store is a thin Cache API wrapper on wasmJs. On the JVM desktop build it’s a directory of files, one per key, each written in HTTP message shape — header lines, a blank line, then the body. Same body-plus-headers contract, so every line of the code above stays common. The Compose UI just polls refresh() on a timer and renders the cached text.

Workbox’s precache and the app-owned Store now live in the same Cache Storage, partitioned by cache name. That is not a problem — it’s the design — as long as the names don’t collide:

The payoff of the separation shows up here: deploying new software swaps the precache and reloads the tab, while the app’s data cache carries across the update completely independently — precisely the behavior you’d expect from a desktop/mobile app.

Everything above can be checked by reasoning. This one you can check with your hands: unplug the network cable with the app running. The app keeps running, the message stays on screen, and when you plug back in, polling resumes on its own.

That sounds like one feature. It is three independent mechanisms that happen to line up, and it is worth knowing which is which — because they fail separately too:

Point 3 deserves a caveat, because the naive version of it is a trap:

Swallow the error and a permanently broken endpoint becomes indistinguishable from a healthy app showing a cached copy. The user sees plausible-looking content that quietly stopped being true. Record the outcome instead, and say so:

There is a sharper version of the same trap, and this one is specific to Kotlin/Wasm. runCatching above is not a stylistic choice — it catches Throwable, and on this target that is the difference between working and broken:

A failed fetch() never arrives as an Exception here. kotlin.js.JsException extends Throwable directly, and Ktor’s JS engine reports fetch failures as kotlin.Error — also a Throwable, also not an Exception. So the throw sails straight past that catch, past the caller, and out of the polling coroutine. The symptom triple is distinctive once you have seen it: the offline indicator never appears, reconnecting the cable fixes nothing, and only a reload brings the app back. And because the identical code is correct on the JVM — where Ktor throws IOException — it passes every test you run on the desktop target.

Catch Throwable and rethrow CancellationException, or use runCatching and leave a comment saying why. While you are there, make sure the loop itself survives: if the throw can end the while, the first blip stops polling for the lifetime of the page.

The UI then shows a small status dot — "live", or "offline — showing cached copy". Give it a label rather than leaving it a bare coloured dot; an 8 dp dot in the corner of an app bar is genuinely missable, and "there was no offline warning" is a bug report you will otherwise receive about an indicator that was working perfectly. Note what that indicator is scoped to: it reports the health of the data poll only. Software freshness is a separate question with a separate mechanism, and collapsing the two into one "offline" lamp would blur the very line this post is about. The cached entry already carries the timestamp it was stored with, so surfacing how stale the data is costs nothing extra.

One check belongs on the deployed site rather than the build output, because it is the one whose failure takes everybody down at once: every URL in the precache manifest must return 200. Workbox installs the manifest atomically — a single 404 fails the entire install, so one missing file does not degrade gracefully, it stops the service worker working for every client. The symptom is maddeningly indirect: updates simply stop happening.

The way this actually happens is someone tidying the deployed directory by hand, and the wasm distribution offers two tempting candidates:

The rule underneath both: never delete files from a deployed distribution. Change what the build emits and redeploy, so the manifest and the directory always agree.

Two more that cost seconds. Ship a tiny version.json and fetch it after every deploy — it is the fastest way to catch the most common deploy mistake there is, uploading yesterday’s directory. And if you want to confirm a config constant reached the bundle, grep the minified JS for it, remembering that 300000 is written 3e5; unrelated numeric constants will match too, so presence of the right one is the signal, not absence of others.