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.
Matthew Raymer
1 month 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