diff --git a/PWA_CHECKLIST.md b/PWA_CHECKLIST.md deleted file mode 100644 index 9e3564f5..00000000 --- a/PWA_CHECKLIST.md +++ /dev/null @@ -1,95 +0,0 @@ -# PWA Launch Checklist - -## Pre-Production - -- [x] **Replace placeholder icons** with branded designs - - ✅ 192x192px and 512x512px icons from boris-favicon.zip - - ✅ Maskable variants (currently same as standard - can add padding if desired) - - Optional: Use [Maskable.app](https://maskable.app/) to test and refine maskable icons - -- [ ] **Test install flow** - - [ ] Chrome/Edge on desktop - - [ ] Chrome on Android - - [ ] Safari on iOS (limited PWA support) - -- [ ] **Test offline functionality** - - [ ] App shell loads when offline - - [ ] Cached images display - - [ ] Cached articles accessible - - [ ] Local relay still works - - [ ] Online/offline toast notifications work - -- [ ] **Run Lighthouse audit** - - [ ] PWA score >90 - - [ ] All installability criteria met - - [ ] No console errors - -- [ ] **Test service worker updates** - - [ ] Deploy new version - - [ ] Verify update notification appears - - [ ] Verify refresh loads new version - -## Production - -- [ ] **Verify manifest serving** - - Check `/manifest.webmanifest` is accessible - - Verify correct MIME type (`application/manifest+json`) - -- [ ] **Verify service worker serving** - - Check `/sw.js` is accessible - - Verify correct cache headers (short cache, must-revalidate) - -- [ ] **Verify icons serving** - - All icon sizes load correctly - - Proper MIME types for PNG files - -- [ ] **Test on real devices** - - [ ] iOS Safari (add to home screen) - - [ ] Android Chrome (install prompt) - - [ ] Desktop Chrome (install button) - - [ ] Desktop Edge (install button) - -## Post-Launch - -- [ ] Monitor service worker registration errors (analytics/logs) -- [ ] Monitor cache hit rates (optional) -- [ ] Gather user feedback on install experience -- [ ] Consider adding advanced PWA features: - - [ ] Web Share Target - - [ ] Background Sync - - [ ] Badging API - - [ ] Push Notifications - -## Known Limitations - -- **iOS Safari**: Limited PWA support, no install prompt (users must "Add to Home Screen" manually) -- **Firefox**: No install prompt, but PWA features work -- **Private/Incognito**: Service workers may be disabled -- **WebSocket**: Not affected by service worker (by design) - -## Troubleshooting - -### Service Worker Not Registering -1. Check browser console for errors -2. Verify `/sw.js` is accessible -3. Check HTTPS is enabled (required for SW) -4. Clear browser cache and reload - -### Install Prompt Not Showing -1. Verify manifest is valid (Chrome DevTools > Application > Manifest) -2. Check all installability criteria (Lighthouse PWA audit) -3. Try in Chrome/Edge (best PWA support) -4. Some browsers require user engagement before showing prompt - -### Offline Not Working -1. Check service worker is active (DevTools > Application > Service Workers) -2. Verify precache manifest was generated (check `dist/sw.js`) -3. Test after first visit (SW needs initial registration) -4. Check network tab shows "(from ServiceWorker)" for cached resources - -### Icons Not Showing -1. Verify icon files exist in `public/` directory -2. Check manifest references correct paths -3. Verify icon files are valid PNG format -4. Clear browser cache and reinstall app - diff --git a/PWA_IMPLEMENTATION.md b/PWA_IMPLEMENTATION.md deleted file mode 100644 index 6c3f5b4c..00000000 --- a/PWA_IMPLEMENTATION.md +++ /dev/null @@ -1,161 +0,0 @@ -# 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-192.png` - PWA icon (192x192) -- `public/icon-512.png` - PWA icon (512x512) -- `public/icon-maskable-192.png` - Maskable PWA icon (192x192) -- `public/icon-maskable-512.png` - Maskable PWA icon (512x512) -- `public/favicon-16x16.png` - Favicon (16x16) -- `public/favicon-32x32.png` - Favicon (32x32) -- `public/favicon.ico` - Multi-size favicon -- `public/apple-touch-icon.png` - iOS home screen icon - -### 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 - -## Icons - -✅ **Branded icons now in place!** - -The following icons have been extracted from `boris-favicon.zip` and are ready: -- `public/icon-192.png` - 192x192px PWA icon (from android-chrome-192x192.png) -- `public/icon-512.png` - 512x512px PWA icon (from android-chrome-512x512.png) -- `public/icon-maskable-192.png` - 192x192px maskable variant -- `public/icon-maskable-512.png` - 512x512px maskable variant -- `public/favicon.ico` - Standard favicon -- `public/favicon-16x16.png` - 16x16 favicon -- `public/favicon-32x32.png` - 32x32 favicon -- `public/apple-touch-icon.png` - iOS home screen icon - -**Note**: The maskable icons currently use the same images as standard icons. If you want optimal maskable appearance with safe area padding, consider creating dedicated maskable variants with ~20% padding on all sides. - -## 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 - -## 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. **Test install flow** on mobile devices (iOS Safari, Android Chrome) -2. **Test offline experience** thoroughly -3. **Monitor service worker** updates in production -4. **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/) -