Shipping a Web Game as a PWA and a Desktop App from One Codebase
All four of my games are web games first, and all four also have Electron builds for macOS and Windows. This post uses two of them as examples: Piko and Ash & Oath, which run in the browser, install as progressive web apps (PWAs) and ship as desktop apps. It's the same code in all three places.
This post covers how that works: the service worker that makes the web version work offline, the Electron wrapper that turns it into a desktop app, and the problems I hit along the way.
Why bother with three versions?
Reach. The games are in beta, and I want as many people as possible to play them. Some players are happy in a browser tab, some want to install the game like an app, and some only trust a proper download. Offering all three means nobody is turned away because the game doesn't come in the form they prefer.
Layer 1: the PWA
A PWA is a website plus two things: a manifest (name, icons, colours) so it can be installed, and a service worker, a script that sits between the page and the network and decides what to cache.
Ash & Oath's service worker uses a different strategy for each type of file:
| Request | Strategy | Why |
|---|---|---|
| App shell (pages, core JS and CSS, icons) | Precached at install | The game opens offline |
Hashed assets (/assets/*) |
Cache-first, stored as they load | Filenames change when content does, so a cached copy is never stale |
| Pages | Network-first, cache fallback | Players get updates, but it still works offline |
| Accounts, saves, payments, downloads | Network only, never cached | Stale data here would be a bug, or worse |
One deliberate choice: the full game is never downloaded up front. The build is hundreds of megabytes, so assets are cached as you meet them. Chapters and models you've already visited keep working offline, without forcing a huge download on someone who just wants to try the game.
The other important detail is the hashed filenames. Vite puts a content hash in every asset's name (warden-a1b2c3.glb), so "cache forever" is safe: a changed file gets a new name. When a new version deploys, the service worker gets a new build version, and old caches are cleaned up.
Layer 2: the desktop app
Both games use Electron and electron-builder. Electron gives you a Chromium window and a Node.js process to control it. Most of the work is deciding what that window is allowed to load and do.
Lock the window down
The game runs with the strictest settings Electron offers:
webPreferences: {
preload: path.join(__dirname, 'preload.cjs'),
contextIsolation: true,
nodeIntegration: false,
sandbox: true,
webSecurity: true,
devTools: !app.isPackaged,
},
The game is just web code. It doesn't need Node.js, and since the desktop app can also load pages from the live site, giving it Node access would be dangerous. A navigation handler only allows the game's own origin, plus a short list of hosts for sign-in and payment. Anything else opens in the player's normal browser.
Serve the bundled game over a custom protocol
Loading the game with file:// URLs breaks things that browsers only allow on secure origins, such as service workers, fetch and some media APIs. Instead, Piko registers its own piko:// scheme as a secure, standard origin and serves the built game from it:
protocol.registerSchemesAsPrivileged([
{ scheme: 'piko', privileges: { standard: true, secure: true, supportFetchAPI: true, corsEnabled: true } },
]);
protocol.handle('piko', (request) => {
const url = new URL(request.url);
const requested = decodeURIComponent(url.pathname).replace(/^\/+/, '');
const filePath = path.resolve(distRoot, path.extname(requested) ? requested : 'index.html');
// Never serve anything outside the built game, whatever the URL says.
if (!filePath.startsWith(`${distRoot}${path.sep}`)) return new Response('Not found', { status: 404 });
return net.fetch(pathToFileURL(filePath).toString());
});
That path check matters. Without it, a crafted URL like piko://app/../../secret could read any file on the player's computer.
Online and offline
The two games handle connectivity differently.
Piko starts from the live website when it can reach it, and falls back to the bundled copy when it can't. Players get the latest version when they're online and a working game when they're not.
Ash & Oath makes the choice explicit, because its saves are bigger and matter more. The desktop app opens on a title screen with Play online and Play offline:
- Online loads the live site inside the app and uses your account and cloud saves.
- Offline runs the bundled game with local saves, with no account and no network.
Online and offline saves are kept strictly separate. Switching modes never copies, merges or overwrites a character, and a failed connection returns you to the title screen with an error rather than quietly starting an offline game.
Sign-in
Sign-in providers often refuse to run inside embedded browsers, so Piko sends sign-in to the player's real browser. When it finishes, the site hands back a one-time ticket through a piko://auth?ticket=… deep link, which the app validates (scheme, host and a strict ticket format) before using it.
The best optimisation: don't download what's already installed
In Ash & Oath's online mode, the game initially downloaded every 3D model from the website, even though the same models were already inside the desktop app. Because model filenames carry a content hash, the app can safely load any model it already has from the installed copy, and fetch from the site only the ones added since that build.
Measured on an M3 MacBook, a cold online new game went from 31.8 seconds to 9–11 seconds.
Releasing
Each desktop release is six packages: a DMG and a ZIP for Apple Silicon and for Intel Macs, plus a Windows installer and a portable EXE. The process:
- Build all six and smoke-test them with isolated profiles, so a test never touches a real save.
- Record each file's exact size and SHA-256 hash.
- Upload the installers to Vercel Blob storage.
- Publish a small JSON manifest that the website reads to show the latest version, file sizes and checksums. The download page updates itself.
- Check the live download links, then remove the previous version.
Signing: not yet
The desktop betas are currently unsigned. On macOS that means the first launch needs a manual approval, and Piko's download page walks players through it: open Privacy & Security in System Settings and click Open Anyway.
That's a deliberate trade-off. Signing and notarisation cost money and add steps to every release, and I'd rather spend that once I know people actually want to play these games. The release scripts are ready for it: Piko's has a signed mode that refuses to publish anything that isn't signed and notarised, and an unsigned mode that warns before publishing a beta.
What I'd tell anyone doing the same
- Hash your asset filenames. It makes PWA caching, CDN caching and the desktop optimisation above all trivial and safe.
- Sandbox the desktop window as if it were a browser, because it is one.
- Use a custom protocol instead of
file://, and check paths. - Be explicit about saves. Separate online and offline progress rather than guessing how to merge them.
- Automate the release checklist. Six packages, checksums and a manifest are too many steps to do by hand every time.