mirror of
https://github.com/dergigi/boris.git
synced 2025-12-17 06:34:24 +01:00
docs: remove temporary PWA launch checklist and implementation summary
This commit is contained in:
Gigi
@@ -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
|
||||
|
||||
@@ -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/)
|
||||
|
||||
Reference in New Issue
Block a user