Skip to content

Add Progressive Web App (PWA) Support #8

@aerumist

Description

@aerumist

Convert the React frontend into an installable Progressive Web App so caregivers can add the dashboard to their phone/tablet home screen and receive a native-app-like experience — even on spotty connections.

Motivation

The caregiver dashboard is a real-time monitoring tool that benefits from always being one tap away. A PWA lets users:

  • Install the app to their home screen (no app store needed)
  • Get a full-screen, native-feeling experience (no browser chrome)
  • Load instantly with a cached app shell, even on flaky Wi-Fi
  • Receive push notifications in the future (lays the groundwork)

Scope

Must Have

  • Web App Manifest (manifest.json) — name, short name, icons, theme/background colours, display: standalone, start URL
  • App Icons — generate the full icon set (192×192, 512×512 + maskable variants)
  • Service Worker via vite-plugin-pwa — precache the app shell (HTML, CSS, JS, fonts)
  • Meta tags in index.html<link rel="manifest">, theme-color, Apple-specific meta tags (apple-mobile-web-app-capable, apple-mobile-web-app-status-bar-style, apple-touch-icon)
  • Offline fallback page — a simple "You are offline" screen when the network is down and the route isn't cached
  • Update prompt — show a toast/banner when a new version is available so the user can refresh

Nice to Have

  • Runtime caching strategy for API responses (NetworkFirst for /api/*) so the last-known state renders offline
  • Background sync — queue failed API writes and replay when back online
  • Push notifications via Web Push API (requires backend changes to store subscriptions and send VAPID-signed payloads)

Technical Notes

  • Tooling: Use vite-plugin-pwa — it wraps Workbox under the hood and integrates cleanly with our Vite build.
  • Config location: Add the plugin config in vite.config.ts alongside the existing React plugin.
  • WebSocket caveat: Service workers cannot intercept WebSocket traffic, so /ws/caregiver will keep working as-is — no special handling needed.
  • Fonts: Google Fonts are loaded via external stylesheet; consider caching the font files with a CacheFirst strategy for offline support.

Acceptance Criteria

  • Running npm run build produces a valid manifest.webmanifest and a service worker in dist/
  • Lighthouse PWA audit passes with no errors
  • App is installable on Chrome (desktop + Android) and Safari (iOS)
  • Offline: cached pages load; uncached routes show the offline fallback
  • Returning users see an update-available prompt when a new build is deployed

Metadata

Metadata

Assignees

Labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions