9.2 KiB

Raw Blame History

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:

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:

npm run build:web:dev
# or
./scripts/build-web.sh --dev

Test Environment (`.env.test`)

Configuration:

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:

npm run build:web:test
# or
./scripts/build-web.sh --test

Production Environment (`.env.production`)

Configuration:

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:

npm run build:web:prod
# or
./scripts/build-web.sh --prod

Technical Implementation

Vite Configuration (`vite.config.web.mts`)

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`)

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:

Environment Files: .env.development, .env.test, .env.production
Vite Mode: Passed via --mode parameter
PWA Status: Always enabled for web platforms (no longer environment-dependent)
Dev Options: Always enabled for consistent testing

Build Script Integration

The build-web.sh script properly handles environment setup:

# 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

Test Environment: Consider PWA-specific test scenarios
Caching Strategy: Review API caching for all environments
Manifest Icons: Ensure all icon sizes are optimized
Service Worker: Add more sophisticated offline strategies

Monitoring Considerations

Installation Metrics: Track PWA installations across environments
Service Worker Performance: Monitor cache hit rates
Offline Usage: Analyze offline functionality usage
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

9.2 KiB Raw Blame History

PWA Build Analysis - Web Environments

Executive Summary

PWA Configuration Overview

Core PWA Setup

Environment-Specific PWA Status

Detailed Environment Analysis

Development Environment (.env.development)

Test Environment (.env.test)

Production Environment (.env.production)

Technical Implementation

Vite Configuration (vite.config.web.mts)

PWA Manifest Configuration (vite.config.utils.mts)

Build Process Analysis

Environment Detection

Build Script Integration

PWA Features by Environment

Development Features

Test Features

Production Features

Recent Changes

PWA Always Enabled

Updated Files

Recommendations

Current State Assessment

Potential Improvements

Monitoring Considerations

Conclusion

9.2 KiB

Raw Blame History

Development Environment (`.env.development`)

Test Environment (`.env.test`)

Production Environment (`.env.production`)

Vite Configuration (`vite.config.web.mts`)

PWA Manifest Configuration (`vite.config.utils.mts`)