Feature Request: Add Progressive Web App (PWA) Support to Monkeytype

[RaviP9973]

Currently, Monkeytype is primarily accessed through a web browser. Users who frequently practice typing may benefit from having Monkeytype installed as a desktop or mobile application.

There is also an opportunity to improve the experience for users with limited or unstable internet connectivity.

Proposed Solution

I would like to propose adding Progressive Web App (PWA) support to Monkeytype.

The implementation could include:

Web App Manifest

1. Add a manifest.webmanifest file.
2. Configure the application name, icons, theme color, and standalone display mode.
3. Use existing Monkeytype branding.

Service Worker

1. Register a service worker to manage application caching.
2. Cache static assets such as JavaScript, CSS, fonts, and other required resources.
3. Provide an appropriate offline fallback.
4. Implement cache versioning and update handling.

Custom Install Banner

1. Display an installation banner when the application is eligible for installation but isn't installed.
2. Use the browser's beforeinstallprompt event where supported.
3. Provide an installation button that triggers the native browser installation prompt.
4. Hide the banner when the application is already installed.
5. Provide installation instructions for browsers that don't support beforeinstallprompt, such as Safari on iOS.

Expected Benefits

1. Users can install Monkeytype directly on their desktop or mobile devices.
2. A standalone application experience without browser tabs and address bars.
3. Faster subsequent loading through effective asset caching.
4. Better accessibility when internet connectivity is unstable.
5. A more app-like experience for regular users.

Implementation Considerations

1. Preserve all existing typing functionality and application behavior.
2. Avoid caching dynamic API responses or user-specific data indiscriminately.
3. Ensure cached assets are invalidated correctly after deployments.
4. Follow the existing project architecture and coding conventions.

Willingness to Contribute

I would be interested in working on this feature and submitting a pull request if the maintainers consider it a suitable addition to the project.

I would appreciate feedback on the proposed approach and any implementation constraints.

[fehmer]

Thanks for the detailed proposal! Good news: most of this is already implemented (see frontend/vite.config.ts + frontend/src/ts/ready.ts):

Already in place

• Web App Manifest — generated at build time by vite-plugin-pwa into manifest.json (injected into the HTML as <link rel="manifest">): name/short name, start URL, display: standalone, theme + background colors, and the existing branding as 512px any + maskable icons.
• Service Worker — Workbox-generated /sw.js, registered on load (skipped in dev builds), with autoUpdate (skipWaiting + clientsClaim) and cleanupOutdatedCaches.
• Static asset caching — all same-origin requests (JS, CSS, fonts, images, HTML, and the same-origin language/quote JSON files) are cached NetworkFirst, so the site is usable offline after the first visit.
• Dynamic data — the API (api.monkeytype.com) is explicitly excluded from caching, and version.json is forced network-only, so we don't cache user-specific data.
• Update handling — the service worker auto-updates on deploy, and the app additionally checks for new releases (GitHub) and purges all caches + shows a version banner when a new version is out. The no-CSS fallback screen even has a "reinstall service worker" escape hatch.

Still missing — this is where a PR would be valuable

1. Custom install banner (your whole third section) — no beforeinstallprompt handling, no install button, no appinstalled/standalone detection, and no Safari instructions today.
2. iOS standalone meta tags — index.html lacks apple-mobile-web-app-capable / -status-bar-style / -title, so "Add to Home Screen" on iOS produces a web clip rather than a true standalone app.
3. Offline fallback page — navigateFallback is deliberately disabled, so only previously-visited routes work offline; a small offline page would complete the offline story.
4. Minor — the manifest only references 512px icons; 192/512 icon pairs already exist in the repo (static/images/favicon/android-chrome-*.png) and could be referenced, and there's no theme-color meta tag / description in the manifest.

So if you'd like to contribute, the install banner (incl. standalone detection + iOS instructions) plus the iOS meta tags would be the natural next step — happy to discuss the approach before you start.

[RaviP9973]

Thanks for reviewing the proposal and explaining what is already implemented!

I'd be happy to contribute to the remaining PWA improvements.

I can work on the following:

1. Custom Install Banner: Handle the beforeinstallprompt event where supported, detect standalone mode, provide an install button, and show browser-specific installation instructions for browsers like Safari on iOS.
2. iOS Support: Add the required Apple-specific meta tags and touch icon configuration to improve the standalone experience on iOS.
3. Offline Fallback: Implement a dedicated offline fallback page for navigation requests while preserving the existing caching strategy.

I'll first review the existing implementation in vite.config.ts, ready.ts, and index.html to ensure the changes integrate cleanly without duplicating existing functionality.

I'll also account for browser-specific limitations, particularly Safari's lack of support for the beforeinstallprompt event.

Please let me know if this scope looks good. I'd be happy to get started and submit a PR!