Browse Source
- Deleted src/registerServiceWorker.ts and all related imports - Cleaned up WebPlatformService and main.web.ts to remove manual SW logic - Updated VitePWA config for correct dev/prod SW handling - Fixed missing FontAwesome download icon in PWA prompt - Updated docs to reflect new PWA registration approach PWA now works reliably in all web environments with zero manual SW code.web-serve-fix
Matthew Raymer
2 weeks ago
23 changed files with 328 additions and 126 deletions
File diff suppressed because one or more lines are too long
@ -0,0 +1,289 @@ |
|||||
|
# PWA Build Analysis - Web Environments |
||||
|
|
||||
|
**Date**: July 15, 2025 |
||||
|
**Author**: Matthew Raymer |
||||
|
**Scope**: Web builds across dev, test, and prod environments |
||||
|
|
||||
|
## Executive Summary |
||||
|
|
||||
|
The TimeSafari application has comprehensive PWA (Progressive Web App) support configured across all web build environments. **PWA functionality is now always enabled for web platforms**, removing the previous environment-specific toggle mechanism. The PWA features are properly integrated and provide consistent functionality across all web builds. |
||||
|
|
||||
|
## PWA Configuration Overview |
||||
|
|
||||
|
### Core PWA Setup |
||||
|
- **Plugin**: `vite-plugin-pwa` with `VitePWA` configuration |
||||
|
- **Service Worker**: Custom service worker with Workbox integration |
||||
|
- **Manifest**: Dynamic PWA manifest with environment-specific settings |
||||
|
- **Registration**: Auto-update registration type |
||||
|
- **Status**: ✅ **Always enabled for web platforms** |
||||
|
|
||||
|
### Environment-Specific PWA Status |
||||
|
|
||||
|
| Environment | PWA Status | Dev Options | Service Worker | Manifest | Install Prompt | |
||||
|
|-------------|------------|-------------|----------------|----------|----------------| |
||||
|
| **Development** | ✅ Always Enabled | ✅ `enabled: true` | ✅ Active | ✅ Generated | ✅ Available | |
||||
|
| **Test** | ✅ Always Enabled | ✅ `enabled: true` | ✅ Active | ✅ Generated | ✅ Available | |
||||
|
| **Production** | ✅ Always Enabled | ✅ `enabled: true` | ✅ Active | ✅ Generated | ✅ Available | |
||||
|
|
||||
|
## Detailed Environment Analysis |
||||
|
|
||||
|
### Development Environment (`.env.development`) |
||||
|
|
||||
|
**Configuration**: |
||||
|
```bash |
||||
|
VITE_DEFAULT_ENDORSER_API_SERVER=http://127.0.0.1:3000 |
||||
|
``` |
||||
|
|
||||
|
**PWA Features**: |
||||
|
- ✅ **Full PWA Support**: Always enabled for development testing |
||||
|
- ✅ **Service Worker**: Active with development optimizations |
||||
|
- ✅ **Manifest**: Generated with development settings |
||||
|
- ✅ **Install Prompt**: Available for testing PWA installation |
||||
|
- ✅ **Dev Options**: `enabled: true` for consistent testing |
||||
|
|
||||
|
**Build Command**: |
||||
|
```bash |
||||
|
npm run build:web:dev |
||||
|
# or |
||||
|
./scripts/build-web.sh --dev |
||||
|
``` |
||||
|
|
||||
|
### Test Environment (`.env.test`) |
||||
|
|
||||
|
**Configuration**: |
||||
|
```bash |
||||
|
VITE_APP_SERVER=https://test.timesafari.app |
||||
|
VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch |
||||
|
``` |
||||
|
|
||||
|
**PWA Features**: |
||||
|
- ✅ **Full PWA Support**: Always enabled for test environment |
||||
|
- ✅ **Service Worker**: Active with test optimizations |
||||
|
- ✅ **Manifest**: Generated and fully utilized |
||||
|
- ✅ **Install Prompt**: Available for test installations |
||||
|
- ✅ **Dev Options**: Enabled for debugging |
||||
|
|
||||
|
**Build Command**: |
||||
|
```bash |
||||
|
npm run build:web:test |
||||
|
# or |
||||
|
./scripts/build-web.sh --test |
||||
|
``` |
||||
|
|
||||
|
### Production Environment (`.env.production`) |
||||
|
|
||||
|
**Configuration**: |
||||
|
```bash |
||||
|
VITE_APP_SERVER=https://timesafari.app |
||||
|
VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch |
||||
|
``` |
||||
|
|
||||
|
**PWA Features**: |
||||
|
- ✅ **Full PWA Support**: Always enabled for production users |
||||
|
- ✅ **Service Worker**: Active with production optimizations |
||||
|
- ✅ **Manifest**: Generated with production settings |
||||
|
- ✅ **Install Prompt**: Available for user installations |
||||
|
- ✅ **Dev Options**: Enabled for production debugging |
||||
|
|
||||
|
**Build Command**: |
||||
|
```bash |
||||
|
npm run build:web:prod |
||||
|
# or |
||||
|
./scripts/build-web.sh --prod |
||||
|
``` |
||||
|
|
||||
|
## Technical Implementation |
||||
|
|
||||
|
### Vite Configuration (`vite.config.web.mts`) |
||||
|
|
||||
|
```typescript |
||||
|
VitePWA({ |
||||
|
registerType: 'autoUpdate', |
||||
|
manifest: appConfig.pwaConfig?.manifest, |
||||
|
// Enable PWA in all web environments for consistent testing |
||||
|
devOptions: { |
||||
|
enabled: true, // ✅ Enable in all environments |
||||
|
type: 'module' |
||||
|
}, |
||||
|
workbox: { |
||||
|
cleanupOutdatedCaches: true, |
||||
|
skipWaiting: true, |
||||
|
clientsClaim: true, |
||||
|
sourcemap: mode !== 'production', |
||||
|
maximumFileSizeToCacheInBytes: 10 * 1024 * 1024, // 10MB |
||||
|
// Environment-specific caching strategies |
||||
|
runtimeCaching: mode === 'production' ? [ |
||||
|
{ |
||||
|
urlPattern: /^https:\/\/api\./, |
||||
|
handler: 'NetworkFirst', |
||||
|
options: { |
||||
|
cacheName: 'api-cache', |
||||
|
expiration: { |
||||
|
maxEntries: 100, |
||||
|
maxAgeSeconds: 60 * 60 * 24 // 24 hours |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
] : [] |
||||
|
} |
||||
|
}) |
||||
|
``` |
||||
|
|
||||
|
### PWA Manifest Configuration (`vite.config.utils.mts`) |
||||
|
|
||||
|
```typescript |
||||
|
manifest: { |
||||
|
name: appName, |
||||
|
short_name: appName, |
||||
|
theme_color: "#4a90e2", |
||||
|
background_color: "#ffffff", |
||||
|
icons: [ |
||||
|
{ |
||||
|
src: "./img/icons/android-chrome-192x192.png", |
||||
|
sizes: "192x192", |
||||
|
type: "image/png", |
||||
|
}, |
||||
|
{ |
||||
|
src: "./img/icons/android-chrome-512x512.png", |
||||
|
sizes: "512x512", |
||||
|
type: "image/png", |
||||
|
}, |
||||
|
{ |
||||
|
src: "./img/icons/android-chrome-maskable-192x192.png", |
||||
|
sizes: "192x192", |
||||
|
type: "image/png", |
||||
|
purpose: "maskable", |
||||
|
}, |
||||
|
{ |
||||
|
src: "./img/icons/android-chrome-maskable-512x512.png", |
||||
|
sizes: "512x512", |
||||
|
type: "image/png", |
||||
|
purpose: "maskable", |
||||
|
}, |
||||
|
], |
||||
|
share_target: { |
||||
|
action: "/share-target", |
||||
|
method: "POST", |
||||
|
enctype: "multipart/form-data", |
||||
|
params: { |
||||
|
files: [ |
||||
|
{ |
||||
|
name: "photo", |
||||
|
accept: ["image/*"], |
||||
|
}, |
||||
|
], |
||||
|
}, |
||||
|
}, |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
## Build Process Analysis |
||||
|
|
||||
|
### Environment Detection |
||||
|
The build system automatically detects the environment and applies appropriate PWA settings: |
||||
|
|
||||
|
1. **Environment Files**: `.env.development`, `.env.test`, `.env.production` |
||||
|
2. **Vite Mode**: Passed via `--mode` parameter |
||||
|
3. **PWA Status**: Always enabled for web platforms (no longer environment-dependent) |
||||
|
4. **Dev Options**: Always enabled for consistent testing |
||||
|
|
||||
|
### Build Script Integration |
||||
|
The `build-web.sh` script properly handles environment setup: |
||||
|
|
||||
|
```bash |
||||
|
# Environment-specific configuration |
||||
|
case $BUILD_MODE in |
||||
|
"production") |
||||
|
export NODE_ENV="production" |
||||
|
;; |
||||
|
"test") |
||||
|
export NODE_ENV="test" |
||||
|
;; |
||||
|
"development"|*) |
||||
|
export NODE_ENV="development" |
||||
|
;; |
||||
|
esac |
||||
|
|
||||
|
# Load environment-specific .env file |
||||
|
local env_file=".env.$BUILD_MODE" |
||||
|
if [ -f "$env_file" ]; then |
||||
|
load_env_file "$env_file" |
||||
|
fi |
||||
|
``` |
||||
|
|
||||
|
## PWA Features by Environment |
||||
|
|
||||
|
### Development Features |
||||
|
- **Hot Reload**: Service worker updates automatically |
||||
|
- **Debug Mode**: Full PWA functionality for testing |
||||
|
- **Local Testing**: Install prompt available |
||||
|
- **Development Server**: PWA features work on localhost |
||||
|
|
||||
|
### Test Features |
||||
|
- **Full PWA**: Complete PWA functionality for testing |
||||
|
- **Service Worker**: Active with test optimizations |
||||
|
- **Manifest**: Generated and fully utilized |
||||
|
- **Install Prompt**: Available for test installations |
||||
|
|
||||
|
### Production Features |
||||
|
- **Full PWA**: Complete Progressive Web App functionality |
||||
|
- **Service Worker**: Production-optimized caching |
||||
|
- **Install Prompt**: Available for user installations |
||||
|
- **API Caching**: Network-first strategy for API calls |
||||
|
- **Offline Support**: Cached resources for offline use |
||||
|
|
||||
|
## Recent Changes |
||||
|
|
||||
|
### PWA Always Enabled |
||||
|
- **Removed**: `VITE_PWA_ENABLED` environment variable (no longer used) |
||||
|
- **Updated**: Service worker registration to always run |
||||
|
- **Simplified**: PWA component logic |
||||
|
- **Consistent**: PWA behavior across all environments |
||||
|
|
||||
|
### Updated Files |
||||
|
- `vite.config.common.mts`: Removed PWA toggle logic |
||||
|
- `src/registerServiceWorker.ts`: Removed (VitePWA handles registration automatically) |
||||
|
- `src/main.web.ts`: Always import service worker |
||||
|
- `src/components/PWAInstallPrompt.vue`: Removed PWA check |
||||
|
- `src/services/platforms/WebPlatformService.ts`: Always return true for PWA |
||||
|
- `scripts/common.sh`: Removed VITE_PWA_ENABLED setting |
||||
|
- Environment files: Removed VITE_PWA_ENABLED variables |
||||
|
- Vite configs: Removed VITE_PWA_ENABLED and VITE_DISABLE_PWA assignments |
||||
|
|
||||
|
## Recommendations |
||||
|
|
||||
|
### Current State Assessment |
||||
|
✅ **Excellent**: PWA is properly configured and always enabled for web |
||||
|
✅ **Consistent**: Same PWA functionality across all environments |
||||
|
✅ **Simplified**: Removed unnecessary conditional logic |
||||
|
✅ **Reliable**: No environment-specific PWA toggles |
||||
|
|
||||
|
### Potential Improvements |
||||
|
1. **Test Environment**: Consider PWA-specific test scenarios |
||||
|
2. **Caching Strategy**: Review API caching for all environments |
||||
|
3. **Manifest Icons**: Ensure all icon sizes are optimized |
||||
|
4. **Service Worker**: Add more sophisticated offline strategies |
||||
|
|
||||
|
### Monitoring Considerations |
||||
|
1. **Installation Metrics**: Track PWA installations across environments |
||||
|
2. **Service Worker Performance**: Monitor cache hit rates |
||||
|
3. **Offline Usage**: Analyze offline functionality usage |
||||
|
4. **Update Success**: Monitor service worker update success rates |
||||
|
|
||||
|
## Conclusion |
||||
|
|
||||
|
The TimeSafari web build system now has **simplified and consistent PWA support** across all environments. PWA functionality is controlled entirely through build-time configuration: |
||||
|
|
||||
|
- **Web platforms**: PWA is always enabled via `vite.config.web.mts` plugin inclusion |
||||
|
- **Native platforms**: PWA is disabled via build-time package exclusion in `vite.config.common.mts` |
||||
|
- **No environment variables**: Removed redundant `VITE_PWA_ENABLED` and `VITE_DISABLE_PWA` variables |
||||
|
|
||||
|
This approach provides a more reliable and predictable user experience with cleaner configuration. |
||||
|
|
||||
|
The implementation follows best practices with proper environment detection, consistent PWA enabling, and comprehensive service worker configuration. The PWA features are well-integrated into the build process and provide a solid foundation for progressive web app functionality across all web environments. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**Analysis Date**: July 15, 2025 |
||||
|
**Status**: ✅ PWA always enabled for web platforms |
||||
|
**Next Review**: After major PWA feature updates |
||||
@ -1,37 +0,0 @@ |
|||||
/* eslint-disable no-console */ |
|
||||
|
|
||||
import { register } from "register-service-worker"; |
|
||||
|
|
||||
// Register service worker if PWA is enabled
|
|
||||
// Enable in all environments for consistent testing and functionality
|
|
||||
if (process.env.VITE_PWA_ENABLED === "true") { |
|
||||
register(`${process.env.BASE_URL}sw.js`, { |
|
||||
ready() { |
|
||||
console.log("Service worker is active."); |
|
||||
}, |
|
||||
registered() { |
|
||||
console.log("Service worker has been registered."); |
|
||||
}, |
|
||||
cached() { |
|
||||
console.log("Content has been cached for offline use."); |
|
||||
}, |
|
||||
updatefound() { |
|
||||
console.log("New content is downloading."); |
|
||||
}, |
|
||||
updated() { |
|
||||
console.log("New content is available; please refresh."); |
|
||||
}, |
|
||||
offline() { |
|
||||
console.log( |
|
||||
"No internet connection found. App is running in offline mode.", |
|
||||
); |
|
||||
}, |
|
||||
error(error) { |
|
||||
console.error("Error during service worker registration:", error); |
|
||||
}, |
|
||||
}); |
|
||||
} else { |
|
||||
console.log( |
|
||||
`Service worker registration skipped - PWA not enabled (VITE_PWA_ENABLED=${process.env.VITE_PWA_ENABLED})`, |
|
||||
); |
|
||||
} |
|
||||
Loading…
Reference in new issue