forked from jsnbuchanan/crowd-funder-for-time-pwa
6b0326b582
- 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.
470 lines
12 KiB
Markdown
470 lines
12 KiB
Markdown
# TimeSafari Build Systems Overview
|
|
|
|
**Author**: Matthew Raymer
|
|
**Date**: 2025-07-11
|
|
**Status**: ✅ **COMPLETE** - All build systems documented and integrated
|
|
|
|
## Overview
|
|
|
|
TimeSafari supports multiple platforms and build targets through a unified build system architecture. This document provides a comprehensive overview of all build systems, their purposes, and how they work together.
|
|
|
|
## Build System Architecture
|
|
|
|
### Platform Support Matrix
|
|
|
|
| Platform | Build Script | Development | Testing | Production | Package Types |
|
|
|----------|--------------|-------------|---------|------------|---------------|
|
|
| **Web** | `build-web.sh` | ✅ Dev Server | ✅ Test Build | ✅ Prod Build | Docker Images |
|
|
| **Android** | `build-android.sh` | ✅ Debug APK | ✅ Test APK | ✅ Release APK/AAB | APK, AAB |
|
|
| **iOS** | `build-ios.sh` | ✅ Debug App | ✅ Test App | ✅ Release App | IPA |
|
|
| **Electron** | `build-electron.sh` | ✅ Dev App | ✅ Test App | ✅ Prod App | AppImage, DEB, DMG, EXE |
|
|
|
|
### Build Script Locations
|
|
|
|
```bash
|
|
scripts/
|
|
├── build-web.sh # Web/PWA builds
|
|
├── build-android.sh # Android mobile builds
|
|
├── build-ios.sh # iOS mobile builds (future)
|
|
├── build-electron.sh # Desktop builds
|
|
└── common.sh # Shared build utilities
|
|
```
|
|
|
|
## Unified Build Pattern
|
|
|
|
All build scripts follow a consistent pattern:
|
|
|
|
### 1. **Environment Setup**
|
|
```bash
|
|
# Set platform-specific environment variables
|
|
VITE_PLATFORM=<platform>
|
|
PWA: automatically enabled for web platforms
|
|
VITE_GIT_HASH=<git-commit-hash>
|
|
```
|
|
|
|
### 2. **Argument Parsing**
|
|
```bash
|
|
# Consistent command-line interface
|
|
./scripts/build-<platform>.sh [--dev|--test|--prod] [options]
|
|
```
|
|
|
|
### 3. **Build Process**
|
|
```bash
|
|
# Standard build flow
|
|
1. Validate environment
|
|
2. Clean build artifacts
|
|
3. Build web assets (Vite)
|
|
4. Platform-specific build
|
|
5. Generate assets
|
|
6. Create packages (if requested)
|
|
```
|
|
|
|
### 4. **Error Handling**
|
|
```bash
|
|
# Consistent exit codes
|
|
1: Cleanup failed
|
|
2: Web build failed
|
|
3: Platform build failed
|
|
4: Asset generation failed
|
|
5: Package creation failed
|
|
```
|
|
|
|
## Web Build System
|
|
|
|
### Purpose
|
|
Builds the web application for browser and PWA deployment.
|
|
|
|
### Key Features
|
|
- **Development Server**: Hot reload with Vite
|
|
- **PWA Support**: Service workers and manifest generation
|
|
- **Docker Integration**: Containerized deployment
|
|
- **Environment Modes**: Development, test, production
|
|
|
|
### Usage Examples
|
|
```bash
|
|
# Development (starts dev server)
|
|
npm run build:web:dev
|
|
|
|
# Production build
|
|
npm run build:web:prod
|
|
|
|
# Docker deployment
|
|
npm run build:web:docker:prod
|
|
```
|
|
|
|
### Output
|
|
- **Development**: Vite dev server at http://localhost:8080
|
|
- **Production**: Static files in `dist/` directory
|
|
- **Docker**: Containerized application image
|
|
|
|
**Documentation**: [Web Build Scripts Guide](build-web-script-integration.md)
|
|
|
|
## Android Build System
|
|
|
|
### Purpose
|
|
Builds Android mobile applications using Capacitor and Gradle.
|
|
|
|
### Key Features
|
|
- **Capacitor Integration**: Web-to-native bridge
|
|
- **Gradle Builds**: APK and AAB generation
|
|
- **Asset Generation**: Icons and splash screens
|
|
- **Device Deployment**: Direct APK installation
|
|
|
|
### Usage Examples
|
|
```bash
|
|
# Development build
|
|
npm run build:android:dev
|
|
|
|
# Production APK
|
|
npm run build:android:prod
|
|
|
|
# Deploy to device
|
|
npm run build:android:deploy
|
|
```
|
|
|
|
### Output
|
|
- **Debug APK**: `android/app/build/outputs/apk/debug/app-debug.apk`
|
|
- **Release APK**: `android/app/build/outputs/apk/release/app-release.apk`
|
|
- **AAB Bundle**: `android/app/build/outputs/bundle/release/app-release.aab`
|
|
|
|
### Device Deployment
|
|
```bash
|
|
# Automatic deployment to connected device
|
|
npm run build:android:deploy
|
|
|
|
# Manual deployment
|
|
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
|
|
```
|
|
|
|
**Documentation**: [Android Build Scripts Guide](android-build-scripts.md)
|
|
|
|
## iOS Build System
|
|
|
|
### Purpose
|
|
Builds iOS mobile applications using Capacitor and Xcode.
|
|
|
|
### Key Features
|
|
- **Capacitor Integration**: Web-to-native bridge
|
|
- **Xcode Integration**: Native iOS builds
|
|
- **Asset Generation**: Icons and splash screens
|
|
- **Simulator Support**: iOS simulator testing
|
|
|
|
### Usage Examples
|
|
```bash
|
|
# Development build
|
|
npm run build:ios:dev
|
|
|
|
# Production build
|
|
npm run build:ios:prod
|
|
|
|
# Open Xcode
|
|
npm run build:ios:studio
|
|
```
|
|
|
|
### Output
|
|
- **Debug App**: `ios/App/build/Debug-iphonesimulator/App.app`
|
|
- **Release App**: `ios/App/build/Release-iphoneos/App.app`
|
|
- **IPA Package**: `ios/App/build/Release-iphoneos/App.ipa`
|
|
|
|
**Documentation**: [iOS Build Scripts Guide](ios-build-scripts.md) *(Future)*
|
|
|
|
## Electron Build System
|
|
|
|
### Purpose
|
|
Builds desktop applications for Windows, macOS, and Linux.
|
|
|
|
### Key Features
|
|
- **Cross-Platform**: Windows, macOS, Linux support
|
|
- **Package Formats**: AppImage, DEB, DMG, EXE
|
|
- **Development Mode**: Direct app execution
|
|
- **Single Instance**: Prevents multiple app instances
|
|
|
|
### Usage Examples
|
|
```bash
|
|
# Development (runs app directly)
|
|
npm run build:electron:dev
|
|
|
|
# Production AppImage
|
|
npm run build:electron:appimage:prod
|
|
|
|
# Production DMG
|
|
npm run build:electron:dmg:prod
|
|
```
|
|
|
|
### Output
|
|
- **Development**: App runs directly (no files created)
|
|
- **Packages**: Executables in `electron/dist/` directory
|
|
- **AppImage**: `TimeSafari-1.0.3-beta.AppImage`
|
|
- **DEB**: `TimeSafari_1.0.3-beta_amd64.deb`
|
|
- **DMG**: `TimeSafari-1.0.3-beta.dmg`
|
|
- **EXE**: `TimeSafari Setup 1.0.3-beta.exe`
|
|
|
|
**Documentation**: [Electron Build Scripts Guide](electron-build-scripts.md)
|
|
|
|
## Environment Management
|
|
|
|
### Environment Variables
|
|
|
|
All build systems use consistent environment variable patterns:
|
|
|
|
```bash
|
|
# Platform identification
|
|
VITE_PLATFORM=web|capacitor|electron
|
|
|
|
# PWA configuration
|
|
PWA: automatically enabled for web platforms
|
|
|
|
# Build information
|
|
VITE_GIT_HASH=<git-commit-hash>
|
|
DEBUG_MIGRATIONS=0|1
|
|
```
|
|
|
|
### Environment Files
|
|
|
|
```bash
|
|
.env.development # Development environment
|
|
.env.test # Testing environment
|
|
.env.production # Production environment
|
|
```
|
|
|
|
### Mode-Specific Configuration
|
|
|
|
Each build mode loads appropriate environment configuration:
|
|
|
|
- **Development**: Local development settings
|
|
- **Test**: Testing environment with test APIs
|
|
- **Production**: Production environment with live APIs
|
|
|
|
## Package.json Integration
|
|
|
|
### Script Organization
|
|
|
|
All build scripts are integrated into `package.json` with consistent naming:
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
// Web builds
|
|
"build:web": "./scripts/build-web.sh",
|
|
"build:web:dev": "./scripts/build-web.sh --dev",
|
|
"build:web:test": "./scripts/build-web.sh --test",
|
|
"build:web:prod": "./scripts/build-web.sh --prod",
|
|
|
|
// Android builds
|
|
"build:android": "./scripts/build-android.sh",
|
|
"build:android:dev": "./scripts/build-android.sh --dev",
|
|
"build:android:test": "./scripts/build-android.sh --test",
|
|
"build:android:prod": "./scripts/build-android.sh --prod",
|
|
|
|
// iOS builds
|
|
"build:ios": "./scripts/build-ios.sh",
|
|
"build:ios:dev": "./scripts/build-ios.sh --dev",
|
|
"build:ios:test": "./scripts/build-ios.sh --test",
|
|
"build:ios:prod": "./scripts/build-ios.sh --prod",
|
|
|
|
// Electron builds
|
|
"build:electron:dev": "./scripts/build-electron.sh --dev",
|
|
"build:electron:test": "./scripts/build-electron.sh --test",
|
|
"build:electron:prod": "./scripts/build-electron.sh --prod"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Legacy Compatibility
|
|
|
|
Legacy scripts are maintained as aliases for backward compatibility:
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
// Legacy Android scripts (aliases)
|
|
"build:capacitor:android": "npm run build:android",
|
|
"build:capacitor:android:dev": "npm run build:android:dev",
|
|
"build:capacitor:android:test": "npm run build:android:test",
|
|
"build:capacitor:android:prod": "npm run build:android:prod"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Build Artifacts
|
|
|
|
### Common Artifacts
|
|
|
|
All build systems generate consistent artifacts:
|
|
|
|
```bash
|
|
dist/ # Web build output
|
|
├── index.html # Main HTML file
|
|
├── assets/ # Compiled assets
|
|
├── manifest.webmanifest # PWA manifest
|
|
└── sw.js # Service worker
|
|
|
|
android/app/build/ # Android build output
|
|
├── outputs/apk/debug/ # Debug APKs
|
|
├── outputs/apk/release/ # Release APKs
|
|
└── outputs/bundle/release/ # AAB bundles
|
|
|
|
ios/App/build/ # iOS build output
|
|
├── Debug-iphonesimulator/ # Debug builds
|
|
└── Release-iphoneos/ # Release builds
|
|
|
|
electron/dist/ # Electron packages
|
|
├── *.AppImage # Linux AppImages
|
|
├── *.deb # Linux DEB packages
|
|
├── *.dmg # macOS DMG packages
|
|
└── *.exe # Windows installers
|
|
```
|
|
|
|
### Asset Generation
|
|
|
|
All platforms generate platform-specific assets:
|
|
|
|
```bash
|
|
# Icons and splash screens
|
|
npx capacitor-assets generate --android
|
|
npx capacitor-assets generate --ios
|
|
|
|
# PWA assets
|
|
npx vite build --config vite.config.web.mts
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Daily Development
|
|
|
|
```bash
|
|
# Web development
|
|
npm run build:web:dev # Starts dev server
|
|
|
|
# Android development
|
|
npm run build:android:dev # Builds debug APK
|
|
npm run build:android:deploy # Deploy to device
|
|
|
|
# Electron development
|
|
npm run build:electron:dev # Runs app directly
|
|
```
|
|
|
|
### Testing Workflow
|
|
|
|
```bash
|
|
# Test all platforms
|
|
npm run build:web:test
|
|
npm run build:android:test
|
|
npm run build:ios:test
|
|
npm run build:electron:test
|
|
```
|
|
|
|
### Production Workflow
|
|
|
|
```bash
|
|
# Build all platforms for production
|
|
npm run build:web:prod
|
|
npm run build:android:prod
|
|
npm run build:ios:prod
|
|
npm run build:electron:prod
|
|
|
|
# Create distribution packages
|
|
npm run build:electron:appimage:prod
|
|
npm run build:electron:dmg:prod
|
|
npm run build:electron:deb:prod
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### Build Failures
|
|
```bash
|
|
# Clean all build artifacts
|
|
npm run clean:all
|
|
|
|
# Rebuild from scratch
|
|
npm run build:<platform>:dev
|
|
```
|
|
|
|
#### Device Connection Issues
|
|
```bash
|
|
# Check Android device connection
|
|
adb devices
|
|
|
|
# Check iOS device connection
|
|
xcrun devicectl list devices
|
|
```
|
|
|
|
#### Environment Issues
|
|
```bash
|
|
# Verify environment variables
|
|
echo $VITE_PLATFORM
|
|
echo "PWA: automatically enabled for web platforms"
|
|
|
|
# Check environment files
|
|
ls -la .env*
|
|
```
|
|
|
|
### Debug Mode
|
|
|
|
Enable verbose logging for all build scripts:
|
|
|
|
```bash
|
|
# Verbose mode
|
|
./scripts/build-<platform>.sh --verbose
|
|
|
|
# Debug environment
|
|
DEBUG_MIGRATIONS=1 npm run build:<platform>:dev
|
|
```
|
|
|
|
## Performance Metrics
|
|
|
|
### Build Times (Typical)
|
|
|
|
| Platform | Development | Production | Package |
|
|
|----------|-------------|------------|---------|
|
|
| **Web** | 350ms | 8s | 12s |
|
|
| **Android** | 45s | 60s | 75s |
|
|
| **iOS** | 60s | 90s | 120s |
|
|
| **Electron** | 15s | 25s | 45s |
|
|
|
|
### Optimization Features
|
|
|
|
- **Incremental Builds**: Only rebuild changed files
|
|
- **Parallel Processing**: Multi-core build optimization
|
|
- **Caching**: Build artifact caching
|
|
- **Asset Optimization**: Image and code minification
|
|
|
|
## Security Considerations
|
|
|
|
### Build Security
|
|
|
|
- **Environment Isolation**: Separate dev/test/prod environments
|
|
- **Secret Management**: Secure handling of API keys
|
|
- **Code Signing**: Digital signatures for packages
|
|
- **Dependency Scanning**: Regular security audits
|
|
|
|
### Distribution Security
|
|
|
|
- **Package Verification**: Checksum validation
|
|
- **Code Signing**: Digital certificates for packages
|
|
- **Update Security**: Secure update mechanisms
|
|
- **Sandboxing**: Platform-specific security isolation
|
|
|
|
## Future Enhancements
|
|
|
|
### Planned Improvements
|
|
|
|
- **CI/CD Integration**: Automated build pipelines
|
|
- **Cross-Platform Testing**: Unified test framework
|
|
- **Performance Monitoring**: Build performance tracking
|
|
- **Asset Optimization**: Advanced image and code optimization
|
|
|
|
### Platform Expansion
|
|
|
|
- **Windows Store**: Microsoft Store packages
|
|
- **Mac App Store**: App Store distribution
|
|
- **Google Play**: Play Store optimization
|
|
- **App Store**: iOS App Store distribution
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-07-11
|
|
**Version**: 1.0.3-beta
|
|
**Status**: Production Ready |