forked from trent_larson/crowd-funder-for-time-pwa
0dcb1d029e
- Consolidate 5 notification-system-* files into doc/notification-system.md - Add web-push cleanup guide and Start-on-Login glossary entry - Configure markdownlint for consistent formatting - Remove web-push references, focus on native OS scheduling Reduces maintenance overhead while preserving all essential information in a single, well-formatted reference document.
552 lines
12 KiB
Markdown
552 lines
12 KiB
Markdown
# TimeSafari Web-Push Cleanup Guide
|
|
|
|
**Status:** 🚀 Native-First Implementation
|
|
**Date:** 2025-01-27T14:30Z (UTC)
|
|
**Author:** Matthew Raymer
|
|
**Scope:** Web-push code cleanup and deprecation
|
|
**Goal:** Remove or quarantine all web-push code paths and mark as deprecated.
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
This document provides a comprehensive cleanup guide for removing web-push code
|
|
paths from TimeSafari. Web-push has been retired for unreliability, and the
|
|
system now focuses on native mobile reliability with Electron best-effort support.
|
|
|
|
---
|
|
|
|
## Cleanup Strategy
|
|
|
|
### Phase 1: Identify Web-Push Code Paths
|
|
|
|
#### Service Worker Files
|
|
|
|
- [ ] `sw_scripts/notification-click.js` - Mark as deprecated
|
|
- [ ] `sw_scripts/` directory - Review for web-push dependencies
|
|
- [ ] Service worker registration code - Remove or quarantine
|
|
|
|
#### Web-Specific Code
|
|
|
|
- [ ] Web push notification handlers
|
|
- [ ] Service worker event listeners
|
|
- [ ] Web notification API usage
|
|
- [ ] Push subscription management
|
|
|
|
#### Configuration Files
|
|
|
|
- [ ] VitePWA plugin configuration
|
|
- [ ] Service worker build configuration
|
|
- [ ] Web push manifest files
|
|
|
|
### Phase 2: Mark as Deprecated
|
|
|
|
#### Code Comments
|
|
|
|
```javascript
|
|
// DEPRECATED: Web-push notification handling
|
|
// This code is kept for reference but not used in production
|
|
// Replaced by Native-First notification system
|
|
```
|
|
|
|
#### Documentation Updates
|
|
|
|
- [ ] Mark web-push sections as deprecated
|
|
- [ ] Add deprecation notices
|
|
- [ ] Update README files
|
|
- [ ] Update API documentation
|
|
|
|
### Phase 3: Remove or Quarantine
|
|
|
|
#### Complete Removal
|
|
|
|
- [ ] Web push subscription code
|
|
- [ ] Service worker notification handlers
|
|
- [ ] Web-specific notification APIs
|
|
- [ ] Push message handling
|
|
|
|
#### Quarantine (Keep for Reference)
|
|
|
|
- [ ] Service worker registration code
|
|
- [ ] Web push configuration
|
|
- [ ] Historical web-push tests
|
|
|
|
---
|
|
|
|
## Detailed Cleanup Tasks
|
|
|
|
### 1. Service Worker Cleanup
|
|
|
|
#### Files to Deprecate
|
|
|
|
**`sw_scripts/notification-click.js`**
|
|
|
|
```javascript
|
|
// DEPRECATED: Service worker notification handling
|
|
// This code is kept for reference but not used in production
|
|
// Replaced by Native-First notification system
|
|
|
|
// Original web-push notification click handler
|
|
self.addEventListener('notificationclick', (event) => {
|
|
// DEPRECATED: Web-push only
|
|
event.notification.close();
|
|
|
|
const slotId = event.notification.data?.slotId;
|
|
const route = slotId ? '/#/daily' : '/#/notifications';
|
|
|
|
event.waitUntil(
|
|
clients.openWindow(route).catch(() => {
|
|
return clients.openWindow('/');
|
|
})
|
|
);
|
|
});
|
|
```
|
|
|
|
**Service Worker Registration**
|
|
|
|
```javascript
|
|
// DEPRECATED: Service worker registration
|
|
// This code is kept for reference but not used in production
|
|
// Replaced by Native-First notification system
|
|
|
|
if ('serviceWorker' in navigator && process.env.VITE_PLATFORM === 'web') {
|
|
// DEPRECATED: Web-push only
|
|
navigator.serviceWorker.register('/sw.js')
|
|
.then(registration => {
|
|
console.log('Service Worker registered:', registration);
|
|
})
|
|
.catch(error => {
|
|
console.error('Service Worker registration failed:', error);
|
|
});
|
|
}
|
|
```
|
|
|
|
### 2. Web Push API Cleanup
|
|
|
|
#### Push Subscription Management
|
|
|
|
```javascript
|
|
// DEPRECATED: Web push subscription management
|
|
// This code is kept for reference but not used in production
|
|
// Replaced by Native-First notification system
|
|
|
|
class WebPushManager {
|
|
// DEPRECATED: Web-push only
|
|
async subscribeToPush() {
|
|
// Implementation kept for reference
|
|
}
|
|
|
|
// DEPRECATED: Web-push only
|
|
async unsubscribeFromPush() {
|
|
// Implementation kept for reference
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Push Message Handling
|
|
|
|
```javascript
|
|
// DEPRECATED: Push message handling
|
|
// This code is kept for reference but not used in production
|
|
// Replaced by Native-First notification system
|
|
|
|
self.addEventListener('push', (event) => {
|
|
// DEPRECATED: Web-push only
|
|
const data = event.data ? event.data.json() : {};
|
|
|
|
const options = {
|
|
body: data.body,
|
|
icon: '/icon-192x192.png',
|
|
badge: '/badge-72x72.png',
|
|
data: data
|
|
};
|
|
|
|
event.waitUntil(
|
|
self.registration.showNotification(data.title, options)
|
|
);
|
|
});
|
|
```
|
|
|
|
### 3. Configuration Cleanup
|
|
|
|
#### VitePWA Plugin Configuration
|
|
|
|
```javascript
|
|
// DEPRECATED: VitePWA plugin configuration
|
|
// This configuration is kept for reference but not used in production
|
|
// Replaced by Native-First notification system
|
|
|
|
import { VitePWA } from 'vite-plugin-pwa'
|
|
|
|
export default defineConfig({
|
|
plugins: [
|
|
VitePWA({
|
|
// DEPRECATED: Web-push only
|
|
registerType: 'autoUpdate',
|
|
workbox: {
|
|
globPatterns: ['**/*.{js,css,html,ico,png,svg}']
|
|
},
|
|
includeAssets: ['favicon.ico', 'apple-touch-icon.png', 'masked-icon.svg'],
|
|
manifest: {
|
|
name: 'TimeSafari',
|
|
short_name: 'TimeSafari',
|
|
description: 'TimeSafari App',
|
|
theme_color: '#ffffff',
|
|
icons: [
|
|
{
|
|
src: 'pwa-192x192.png',
|
|
sizes: '192x192',
|
|
type: 'image/png'
|
|
}
|
|
]
|
|
}
|
|
})
|
|
]
|
|
})
|
|
```
|
|
|
|
#### Service Worker Build Configuration
|
|
|
|
```javascript
|
|
// DEPRECATED: Service worker build configuration
|
|
// This configuration is kept for reference but not used in production
|
|
// Replaced by Native-First notification system
|
|
|
|
export default defineConfig({
|
|
build: {
|
|
rollupOptions: {
|
|
input: {
|
|
// DEPRECATED: Web-push only
|
|
sw: 'sw_scripts/notification-click.js'
|
|
}
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
### 4. Test Cleanup
|
|
|
|
#### Web Push Tests
|
|
|
|
```javascript
|
|
// DEPRECATED: Web push tests
|
|
// These tests are kept for reference but not used in production
|
|
// Replaced by Native-First notification system
|
|
|
|
describe('Web Push Notifications (DEPRECATED)', () => {
|
|
// DEPRECATED: Web-push only
|
|
it('should handle push notifications', async () => {
|
|
// Test implementation kept for reference
|
|
});
|
|
|
|
// DEPRECATED: Web-push only
|
|
it('should handle notification clicks', async () => {
|
|
// Test implementation kept for reference
|
|
});
|
|
});
|
|
```
|
|
|
|
#### Service Worker Tests
|
|
|
|
```javascript
|
|
// DEPRECATED: Service worker tests
|
|
// These tests are kept for reference but not used in production
|
|
// Replaced by Native-First notification system
|
|
|
|
describe('Service Worker (DEPRECATED)', () => {
|
|
// DEPRECATED: Web-push only
|
|
it('should register service worker', async () => {
|
|
// Test implementation kept for reference
|
|
});
|
|
|
|
// DEPRECATED: Web-push only
|
|
it('should handle push events', async () => {
|
|
// Test implementation kept for reference
|
|
});
|
|
});
|
|
```
|
|
|
|
### 5. Documentation Cleanup
|
|
|
|
#### README Updates
|
|
|
|
```markdown
|
|
# TimeSafari Native-First Notification System
|
|
|
|
## Web-Push Status: DEPRECATED
|
|
|
|
Web-push has been retired for unreliability. The system now focuses on native mobile reliability with Electron best-effort support.
|
|
|
|
### Deprecated Features
|
|
- ❌ Web push notifications
|
|
- ❌ Service worker notification handling
|
|
- ❌ Web notification API
|
|
|
|
### Active Features
|
|
- ✅ Native mobile notifications (Android/iOS)
|
|
- ✅ Electron notifications (best-effort)
|
|
- ✅ OS-scheduled background prefetch
|
|
- ✅ Rolling window safety
|
|
```
|
|
|
|
#### API Documentation Updates
|
|
|
|
```markdown
|
|
## Notification API (Native-First)
|
|
|
|
### Deprecated Methods
|
|
- `subscribeToPush()` - DEPRECATED: Web-push only
|
|
- `unsubscribeFromPush()` - DEPRECATED: Web-push only
|
|
- `handlePushMessage()` - DEPRECATED: Web-push only
|
|
|
|
### Active Methods
|
|
- `scheduleExact()` - Native exact scheduling
|
|
- `scheduleWindow()` - Native windowed scheduling
|
|
- `schedulePrefetch()` - Native background prefetch
|
|
```
|
|
|
|
---
|
|
|
|
## File-by-File Cleanup Checklist
|
|
|
|
### Service Worker Files
|
|
|
|
- [ ] `sw_scripts/notification-click.js` - Mark as deprecated
|
|
- [ ] `sw_scripts/` directory - Review for web-push dependencies
|
|
- [ ] Service worker build configuration - Remove or quarantine
|
|
|
|
### Web-Specific Code
|
|
|
|
- [ ] `src/main.web.ts` - Remove service worker registration
|
|
- [ ] `src/services/webPush.ts` - Mark as deprecated
|
|
- [ ] `src/utils/serviceWorker.ts` - Mark as deprecated
|
|
- [ ] Web notification API usage - Remove or quarantine
|
|
|
|
### Configuration Files
|
|
|
|
- [ ] `vite.config.web.mts` - Remove VitePWA plugin
|
|
- [ ] `package.json` - Remove web-push dependencies
|
|
- [ ] `public/manifest.json` - Mark as deprecated
|
|
- [ ] Service worker build scripts - Remove or quarantine
|
|
|
|
### Test Files
|
|
|
|
- [ ] `test-playwright/web-push.spec.ts` - Mark as deprecated
|
|
- [ ] `test/services/webPush.test.ts` - Mark as deprecated
|
|
- [ ] Service worker tests - Mark as deprecated
|
|
|
|
### Documentation Files
|
|
|
|
- [ ] `README.md` - Update to reflect native-first approach
|
|
- [ ] `doc/web-push.md` - Mark as deprecated
|
|
- [ ] API documentation - Remove web-push references
|
|
|
|
---
|
|
|
|
## Dependencies to Remove
|
|
|
|
### NPM Packages
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
// DEPRECATED: Web-push only
|
|
"web-push": "^7.4.0",
|
|
"vite-plugin-pwa": "^0.17.0"
|
|
},
|
|
"devDependencies": {
|
|
// DEPRECATED: Web-push only
|
|
"workbox-webpack-plugin": "^6.5.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Build Scripts
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
// DEPRECATED: Web-push only
|
|
"build:sw": "workbox generateSW",
|
|
"test:sw": "jest --testPathPattern=serviceWorker"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Migration Guide
|
|
|
|
### From Web-Push to Native-First
|
|
|
|
#### Step 1: Remove Web-Push Dependencies
|
|
|
|
```bash
|
|
# Remove web-push packages
|
|
npm uninstall web-push vite-plugin-pwa workbox-webpack-plugin
|
|
|
|
# Remove service worker files
|
|
rm -rf sw_scripts/
|
|
rm -f public/sw.js
|
|
rm -f public/workbox-*.js
|
|
```
|
|
|
|
#### Step 2: Update Configuration
|
|
|
|
```javascript
|
|
// Remove VitePWA plugin from vite.config.web.mts
|
|
export default defineConfig({
|
|
plugins: [
|
|
// Remove VitePWA plugin
|
|
// VitePWA({ ... })
|
|
]
|
|
})
|
|
```
|
|
|
|
#### Step 3: Update Service Registration
|
|
|
|
```javascript
|
|
// Remove service worker registration from main.web.ts
|
|
// if ('serviceWorker' in navigator) {
|
|
// navigator.serviceWorker.register('/sw.js')
|
|
// }
|
|
```
|
|
|
|
#### Step 4: Update Tests
|
|
|
|
```javascript
|
|
// Remove web-push tests
|
|
// describe('Web Push Notifications', () => { ... })
|
|
```
|
|
|
|
---
|
|
|
|
## Verification Checklist
|
|
|
|
### Code Removal Verification
|
|
|
|
- [ ] No web-push imports remain
|
|
- [ ] No service worker registration code
|
|
- [ ] No push subscription management
|
|
- [ ] No web notification API usage
|
|
- [ ] No VitePWA plugin configuration
|
|
|
|
### Documentation Verification
|
|
|
|
- [ ] All web-push references marked as deprecated
|
|
- [ ] README updated to reflect native-first approach
|
|
- [ ] API documentation updated
|
|
- [ ] Test documentation updated
|
|
|
|
### Build Verification
|
|
|
|
- [ ] Web build succeeds without service worker
|
|
- [ ] No service worker files generated
|
|
- [ ] No web-push dependencies in bundle
|
|
- [ ] Native builds work correctly
|
|
|
|
### Test Verification
|
|
|
|
- [ ] Web-push tests are marked as deprecated
|
|
- [ ] Native notification tests pass
|
|
- [ ] No web-push test failures
|
|
- [ ] Test suite runs successfully
|
|
|
|
---
|
|
|
|
## Rollback Plan
|
|
|
|
### Emergency Rollback
|
|
|
|
If native-first implementation fails, web-push code can be restored:
|
|
|
|
#### 1. **Restore Dependencies**
|
|
|
|
```bash
|
|
npm install web-push vite-plugin-pwa workbox-webpack-plugin
|
|
```
|
|
|
|
#### 2. **Restore Service Worker Files**
|
|
|
|
```bash
|
|
git checkout HEAD~1 -- sw_scripts/
|
|
git checkout HEAD~1 -- public/sw.js
|
|
```
|
|
|
|
#### 3. **Restore Configuration**
|
|
|
|
```bash
|
|
git checkout HEAD~1 -- vite.config.web.mts
|
|
git checkout HEAD~1 -- package.json
|
|
```
|
|
|
|
#### 4. **Restore Tests**
|
|
|
|
```bash
|
|
git checkout HEAD~1 -- test-playwright/web-push.spec.ts
|
|
git checkout HEAD~1 -- test/services/webPush.test.ts
|
|
```
|
|
|
|
### Rollback Verification
|
|
|
|
- [ ] Web-push functionality restored
|
|
- [ ] Service worker registration works
|
|
- [ ] Push notifications work
|
|
- [ ] Tests pass
|
|
|
|
---
|
|
|
|
## Post-Cleanup Tasks
|
|
|
|
### Code Review
|
|
|
|
- [ ] Review all changes for completeness
|
|
- [ ] Verify no web-push code remains
|
|
- [ ] Check for orphaned references
|
|
- [ ] Validate native-first implementation
|
|
|
|
### Testing
|
|
|
|
- [ ] Run full test suite
|
|
- [ ] Verify native notifications work
|
|
- [ ] Check Electron functionality
|
|
- [ ] Validate mobile builds
|
|
|
|
### Documentation
|
|
|
|
- [ ] Update all documentation
|
|
- [ ] Remove web-push references
|
|
- [ ] Update API documentation
|
|
- [ ] Update user guides
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
### Complete Web-Push Removal
|
|
|
|
- [ ] All web-push code marked as deprecated
|
|
- [ ] Service worker files quarantined
|
|
- [ ] Dependencies removed
|
|
- [ ] Configuration updated
|
|
|
|
### Native-First Implementation
|
|
|
|
- [ ] Native notifications work on Android
|
|
- [ ] Native notifications work on iOS
|
|
- [ ] Electron notifications work
|
|
- [ ] Background prefetch works
|
|
|
|
### Documentation Updated
|
|
|
|
- [ ] All docs reflect native-first approach
|
|
- [ ] Web-push marked as deprecated
|
|
- [ ] Migration guide provided
|
|
- [ ] Rollback plan documented
|
|
|
|
---
|
|
|
|
_This cleanup guide provides comprehensive instructions for removing web-push
|
|
code paths from TimeSafari. Web-push has been retired for unreliability, and the
|
|
system now focuses on native mobile reliability with Electron best-effort support._
|