aljaz/boris
1
1
Fork 0
mirror of https://github.com/dergigi/boris.git synced 2025-12-16 22:24:25 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: remove temporary PWA launch checklist and implementation summary

Browse Source
This commit is contained in:
Gigi
2025-10-12 07:18:20 +01:00
parent 20b4658bef
commit fd374cd705
2 changed files with 0 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
PWA_CHECKLIST.md
View File

@@ -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

161
PWA_IMPLEMENTATION.md
View File

@@ -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/)