From 489e4803948ceebd2e68e9e3fdf577fe6266a454 Mon Sep 17 00:00:00 2001 From: Gigi Date: Sat, 11 Oct 2025 20:42:29 +0100 Subject: [PATCH] docs: add PWA implementation summary and guide --- PWA_IMPLEMENTATION.md | 152 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 PWA_IMPLEMENTATION.md diff --git a/PWA_IMPLEMENTATION.md b/PWA_IMPLEMENTATION.md new file mode 100644 index 00000000..a4be1037 --- /dev/null +++ b/PWA_IMPLEMENTATION.md @@ -0,0 +1,152 @@ +# PWA Implementation Summary + +Boris has been successfully upgraded to a full Progressive Web App (PWA)! + +## What Was Implemented + +### 1. Web App Manifest +- **File**: `public/manifest.webmanifest` +- Includes app name, description, theme colors, and icon references +- Configured for standalone display mode +- Linked in `index.html` with theme-color meta tag + +### 2. Service Worker with Workbox +- **File**: `src/sw.ts` +- **Plugin**: `vite-plugin-pwa` with injectManifest strategy +- **Features**: + - Precaching of app shell (HTML, CSS, JS assets) + - Runtime caching for cross-origin images (30-day cache, max 300 entries) + - Runtime caching for cross-origin article HTML (14-day cache, max 100 entries) + - SPA navigation fallback for offline app loading + - Automatic cleanup of old caches + - **WebSocket traffic is NOT intercepted** - relay functionality preserved + +### 3. PWA Install Experience +- **Hook**: `src/hooks/usePWAInstall.ts` +- **Component**: `src/components/Settings/PWASettings.tsx` +- Captures `beforeinstallprompt` event +- Shows install button in Settings when app is installable +- Displays confirmation when app is already installed + +### 4. Online/Offline Status +- **Hook**: `src/hooks/useOnlineStatus.ts` +- Monitors `navigator.onLine` status +- Shows toast notification when going offline +- Integrated into main App component + +### 5. Service Worker Updates +- Checks for updates hourly +- Shows toast notification when new version is available +- User can refresh to get latest version + +## Files Created/Modified + +### New Files +- `src/sw.ts` - Workbox service worker +- `src/hooks/usePWAInstall.ts` - Install prompt hook +- `src/hooks/useOnlineStatus.ts` - Online status monitoring +- `src/components/Settings/PWASettings.tsx` - Install UI +- `public/manifest.webmanifest` - Web app manifest +- `public/icon-*.png` - PWA icons (placeholders) + +### Modified Files +- `vite.config.ts` - Added VitePWA plugin configuration +- `index.html` - Added manifest link and theme-color +- `src/main.tsx` - Enhanced SW registration +- `src/App.tsx` - Added online/offline monitoring +- `src/components/Settings.tsx` - Added PWA settings section +- `package.json` - Added PWA dependencies + +## Icon Placeholders + +⚠️ **IMPORTANT**: Replace placeholder icons with proper branded designs! + +Current placeholders are minimal 1x1 pixel images. You need: +- `public/icon-192.png` - 192x192px app icon +- `public/icon-512.png` - 512x512px app icon +- `public/icon-maskable-192.png` - 192x192px with safe area padding +- `public/icon-maskable-512.png` - 512x512px with safe area padding + +**Maskable icons** should have ~20% padding on all sides to ensure they look good on all devices. + +## Testing PWA Functionality + +### Local Development +```bash +npm run build +npm run preview # or serve the dist/ folder +``` + +### What to Test +1. **Install prompt**: Visit in Chrome/Edge, check for install button in Settings +2. **Offline mode**: Disconnect network, verify app shell loads +3. **Cached images**: View articles with images, go offline, images still load +4. **Cached articles**: View external articles, go offline, articles still available +5. **Relay connectivity**: Verify local relay and WebSocket connections work +6. **Updates**: Deploy new version, verify update notification appears + +### Lighthouse PWA Audit +Run in Chrome DevTools: +1. Open DevTools (F12) +2. Go to Lighthouse tab +3. Select "Progressive Web App" category +4. Run audit + +Expected scores: +- ✅ Installable +- ✅ PWA Optimized +- ✅ Works offline +- ⚠️ Icons (will pass after replacing placeholders) + +## Build Output + +The build process now: +1. Compiles TypeScript and bundles assets +2. Generates Workbox service worker from `src/sw.ts` +3. Injects precache manifest with all app assets +4. Outputs `dist/sw.js` and `dist/manifest.webmanifest` + +Build command: +```bash +npm run build +``` + +## Deployment Notes + +### Vercel/Cloudflare/Netlify +- No special configuration needed +- `_headers`, `_redirects`, `_routes.json` already excluded from precache +- Service worker will be served at `/sw.js` +- Manifest will be served at `/manifest.webmanifest` + +### CDN Considerations +- Set proper cache headers for `sw.js` (short cache, must-revalidate) +- App assets can have long cache (they're versioned) +- Icons and manifest can have moderate cache (1 hour - 1 day) + +## Existing Functionality Preserved + +✅ **Local Relay**: WebSocket connections not intercepted by SW +✅ **Airplane Mode**: Existing offline sync functionality intact +✅ **Image Caching**: Behavior preserved, now using Workbox +✅ **Nostr Events**: All relay operations work as before + +## Next Steps + +1. **Replace icon placeholders** with branded designs +2. **Test install flow** on mobile devices (iOS Safari, Android Chrome) +3. **Test offline experience** thoroughly +4. **Monitor service worker** updates in production +5. **Consider adding**: + - Web Share Target (share to Boris from system share sheet) + - Background Sync (queue writes when offline) + - Badging API (unread counts on app icon) + - Push notifications (optional, requires push service) + +## Resources + +- [PWA Documentation](https://web.dev/progressive-web-apps/) +- [vite-plugin-pwa Docs](https://vite-pwa-org.netlify.app/) +- [Workbox Documentation](https://developers.google.com/web/tools/workbox) +- [Maskable Icons](https://maskable.app/) +