forked from trent_larson/crowd-funder-for-time-pwa
refactor: implement clean modular Electron build system
Replace chained npm commands with single build-electron.sh script supporting multiple build modes (dev/test/prod), platforms (windows/mac/linux), and package types (appimage/deb/dmg). Add platform validation to prevent cross-platform build issues and integrate cleaning functionality. - Replace 15+ chained npm scripts with single modular build script - Add platform detection and validation with early failure on mismatch - Support environment-specific builds (development/test/production) - Add comprehensive documentation in docs/electron-build-patterns.md - Update BUILDING.md with new build patterns and examples - Remove legacy electron:build:* scripts and consolidate under build:electron:* - Add clean:electron script integrated into build process - Improve error handling and user feedback throughout build process This refactoring follows DRY principles, eliminates command chaining, and provides a more maintainable and user-friendly build system.
This commit is contained in:
Matthew Raymer
533
BUILDING.md
533
BUILDING.md
@@ -204,54 +204,373 @@ docker run -d \
|
||||
|
||||
## Desktop Build (Electron)
|
||||
|
||||
### Linux Build
|
||||
TimeSafari's Electron build system provides comprehensive desktop application
|
||||
packaging and distribution capabilities across Windows, macOS, and Linux
|
||||
platforms. The system supports multiple build modes, environment
|
||||
configurations, and package formats.
|
||||
|
||||
1. Build the electron app in production mode:
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
npm run build:electron-prod
|
||||
```
|
||||
#### Development Build
|
||||
|
||||
2. Package the Electron app for Linux:
|
||||
```bash
|
||||
# Start development build (runs app)
|
||||
npm run build:electron:dev
|
||||
|
||||
```bash
|
||||
# For AppImage (recommended)
|
||||
npm run electron:build-linux
|
||||
# Development build only
|
||||
npm run build:electron --dev
|
||||
```
|
||||
|
||||
# For .deb package
|
||||
npm run electron:build-linux-deb
|
||||
```
|
||||
#### Production Build
|
||||
|
||||
3. The packaged applications will be in `dist-electron-packages/`:
|
||||
- AppImage: `dist-electron-packages/TimeSafari-x.x.x.AppImage`
|
||||
- DEB: `dist-electron-packages/timesafari_x.x.x_amd64.deb`
|
||||
```bash
|
||||
# Production build for all platforms
|
||||
npm run build:electron:prod
|
||||
|
||||
### macOS Build
|
||||
# Platform-specific production builds
|
||||
npm run build:electron:windows:prod
|
||||
npm run build:electron:mac:prod
|
||||
npm run build:electron:linux:prod
|
||||
```
|
||||
|
||||
1. Build the electron app in production mode:
|
||||
#### Package-Specific Builds
|
||||
|
||||
```bash
|
||||
npm run build:web
|
||||
npm run build:electron
|
||||
npm run electron:build-mac
|
||||
```
|
||||
```bash
|
||||
# AppImage for Linux
|
||||
npm run build:electron:appimage:prod
|
||||
|
||||
2. Package the Electron app for macOS:
|
||||
# DEB package for Debian/Ubuntu
|
||||
npm run build:electron:deb:prod
|
||||
|
||||
```bash
|
||||
# For Intel Macs
|
||||
npm run electron:build-mac
|
||||
# DMG for macOS
|
||||
npm run build:electron:dmg:prod
|
||||
```
|
||||
|
||||
# For Universal build (Intel + Apple Silicon)
|
||||
npm run electron:build-mac-universal
|
||||
```
|
||||
#### Direct Script Usage
|
||||
|
||||
3. The packaged applications will be in `dist-electron-packages/`:
|
||||
- `.app` bundle: `TimeSafari.app`
|
||||
- `.dmg` installer: `TimeSafari-x.x.x.dmg`
|
||||
- `.zip` archive: `TimeSafari-x.x.x-mac.zip`
|
||||
```bash
|
||||
# Direct script usage (no npm chaining)
|
||||
./scripts/build-electron.sh --dev # Development build
|
||||
./scripts/build-electron.sh --test # Test build
|
||||
./scripts/build-electron.sh --prod # Production build
|
||||
./scripts/build-electron.sh --prod --windows # Windows production
|
||||
./scripts/build-electron.sh --test --appimage # Linux AppImage test
|
||||
./scripts/build-electron.sh --dev --mac # macOS development
|
||||
./scripts/build-electron.sh --prod --dmg # macOS DMG production
|
||||
```
|
||||
|
||||
### Code Signing and Notarization (macOS)
|
||||
### Build Architecture
|
||||
|
||||
The Electron build process follows a multi-stage approach:
|
||||
|
||||
```
|
||||
1. Web Build (Vite) → 2. Capacitor Sync → 3. TypeScript Compile → 4. Package
|
||||
```
|
||||
|
||||
**Stage 1: Web Build**
|
||||
- Vite builds web assets with Electron-specific configuration
|
||||
- Environment variables loaded based on build mode
|
||||
- Assets optimized for desktop application
|
||||
|
||||
**Stage 2: Capacitor Sync**
|
||||
- Copies web assets to Electron app directory
|
||||
- Syncs Capacitor configuration and plugins
|
||||
- Prepares native module bindings
|
||||
|
||||
**Stage 3: TypeScript Compile**
|
||||
- Compiles Electron main process TypeScript
|
||||
- Rebuilds native modules for target platform
|
||||
- Generates production-ready JavaScript
|
||||
|
||||
**Stage 4: Package Creation**
|
||||
- Creates platform-specific installers
|
||||
- Generates distribution packages
|
||||
- Signs applications (when configured)
|
||||
|
||||
### Build Modes
|
||||
|
||||
#### Development Mode
|
||||
|
||||
**Purpose**: Local development and testing
|
||||
**Command**: `npm run build:electron:dev`
|
||||
**Features**:
|
||||
- Hot reload enabled
|
||||
- Debug tools available
|
||||
- Development logging
|
||||
- Unoptimized assets
|
||||
|
||||
#### Testing Mode
|
||||
|
||||
**Purpose**: Staging and testing environments
|
||||
**Command**: `npm run build:electron -- --mode test`
|
||||
**Features**:
|
||||
- Test API endpoints
|
||||
- Staging configurations
|
||||
- Optimized for testing
|
||||
- Debug information available
|
||||
|
||||
#### Production Mode
|
||||
|
||||
**Purpose**: Production deployment
|
||||
**Command**: `npm run build:electron -- --mode production`
|
||||
**Features**:
|
||||
- Production optimizations
|
||||
- Code minification
|
||||
- Security hardening
|
||||
- Performance optimizations
|
||||
|
||||
### Platform-Specific Builds
|
||||
|
||||
#### Windows Builds
|
||||
|
||||
**Target Platforms**: Windows 10/11 (x64)
|
||||
**Package Formats**: NSIS installer, portable executable
|
||||
|
||||
```bash
|
||||
# Windows development build
|
||||
npm run build:electron:windows:dev
|
||||
|
||||
# Windows test build
|
||||
npm run build:electron:windows:test
|
||||
|
||||
# Windows production build
|
||||
npm run build:electron:windows:prod
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- NSIS installer with custom options
|
||||
- Desktop and Start Menu shortcuts
|
||||
- Elevation permissions for installation
|
||||
- Custom installation directory support
|
||||
|
||||
#### macOS Builds
|
||||
|
||||
**Target Platforms**: macOS 10.15+ (x64, arm64)
|
||||
**Package Formats**: DMG installer, app bundle
|
||||
|
||||
```bash
|
||||
# macOS development build
|
||||
npm run build:electron:mac:dev
|
||||
|
||||
# macOS test build
|
||||
npm run build:electron:mac:test
|
||||
|
||||
# macOS production build
|
||||
npm run build:electron:mac:prod
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- Universal binary (x64 + arm64)
|
||||
- DMG installer with custom branding
|
||||
- App Store compliance (when configured)
|
||||
- Code signing support
|
||||
|
||||
#### Linux Builds
|
||||
|
||||
**Target Platforms**: Ubuntu 18.04+, Debian 10+, Arch Linux
|
||||
**Package Formats**: AppImage, DEB, RPM
|
||||
|
||||
```bash
|
||||
# Linux development build
|
||||
npm run build:electron:linux:dev
|
||||
|
||||
# Linux test build
|
||||
npm run build:electron:linux:test
|
||||
|
||||
# Linux production build
|
||||
npm run build:electron:linux:prod
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- AppImage for universal distribution
|
||||
- DEB package for Debian-based systems
|
||||
- RPM package for Red Hat-based systems
|
||||
- Desktop integration
|
||||
|
||||
### Package-Specific Builds
|
||||
|
||||
#### AppImage Package
|
||||
|
||||
**Format**: Self-contained Linux executable
|
||||
**Distribution**: Universal Linux distribution
|
||||
|
||||
```bash
|
||||
# AppImage development build
|
||||
npm run build:electron:appimage:dev
|
||||
|
||||
# AppImage test build
|
||||
npm run build:electron:appimage:test
|
||||
|
||||
# AppImage production build
|
||||
npm run build:electron:appimage:prod
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Single file distribution
|
||||
- No installation required
|
||||
- Portable across Linux distributions
|
||||
- Automatic updates support
|
||||
|
||||
#### DEB Package
|
||||
|
||||
**Format**: Debian package installer
|
||||
**Distribution**: Debian-based Linux systems
|
||||
|
||||
```bash
|
||||
# DEB development build
|
||||
npm run build:electron:deb:dev
|
||||
|
||||
# DEB test build
|
||||
npm run build:electron:deb:test
|
||||
|
||||
# DEB production build
|
||||
npm run build:electron:deb:prod
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Native package management
|
||||
- Dependency resolution
|
||||
- System integration
|
||||
- Easy installation/uninstallation
|
||||
|
||||
#### DMG Package
|
||||
|
||||
**Format**: macOS disk image
|
||||
**Distribution**: macOS systems
|
||||
|
||||
```bash
|
||||
# DMG development build
|
||||
npm run build:electron:dmg:dev
|
||||
|
||||
# DMG test build
|
||||
npm run build:electron:dmg:test
|
||||
|
||||
# DMG production build
|
||||
npm run build:electron:dmg:prod
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Native macOS installer
|
||||
- Custom branding and layout
|
||||
- Drag-and-drop installation
|
||||
- Code signing support
|
||||
|
||||
### Build Scripts Reference
|
||||
|
||||
#### Main Build Scripts
|
||||
|
||||
```bash
|
||||
# Development builds
|
||||
npm run build:electron:dev # Development build and run
|
||||
npm run build:electron --dev # Development build only
|
||||
|
||||
# Testing builds
|
||||
npm run build:electron:test # Test environment build
|
||||
|
||||
# Production builds
|
||||
npm run build:electron:prod # Production environment build
|
||||
```
|
||||
|
||||
#### Platform-Specific Scripts
|
||||
|
||||
```bash
|
||||
# Windows builds
|
||||
npm run build:electron:windows # Windows production build
|
||||
npm run build:electron:windows:dev # Windows development build
|
||||
npm run build:electron:windows:test # Windows test build
|
||||
npm run build:electron:windows:prod # Windows production build
|
||||
|
||||
# macOS builds
|
||||
npm run build:electron:mac # macOS production build
|
||||
npm run build:electron:mac:dev # macOS development build
|
||||
npm run build:electron:mac:test # macOS test build
|
||||
npm run build:electron:mac:prod # macOS production build
|
||||
|
||||
# Linux builds
|
||||
npm run build:electron:linux # Linux production build
|
||||
npm run build:electron:linux:dev # Linux development build
|
||||
npm run build:electron:linux:test # Linux test build
|
||||
npm run build:electron:linux:prod # Linux production build
|
||||
```
|
||||
|
||||
#### Package-Specific Scripts
|
||||
|
||||
```bash
|
||||
# AppImage builds
|
||||
npm run build:electron:appimage # Linux AppImage production build
|
||||
npm run build:electron:appimage:dev # AppImage development build
|
||||
npm run build:electron:appimage:test # AppImage test build
|
||||
npm run build:electron:appimage:prod # AppImage production build
|
||||
|
||||
# DEB builds
|
||||
npm run build:electron:deb # Debian package production build
|
||||
npm run build:electron:deb:dev # DEB development build
|
||||
npm run build:electron:deb:test # DEB test build
|
||||
npm run build:electron:deb:prod # DEB production build
|
||||
|
||||
# DMG builds
|
||||
npm run build:electron:dmg # macOS DMG production build
|
||||
npm run build:electron:dmg:dev # DMG development build
|
||||
npm run build:electron:dmg:test # DMG test build
|
||||
npm run build:electron:dmg:prod # DMG production build
|
||||
```
|
||||
|
||||
#### Direct Script Usage
|
||||
|
||||
All npm scripts use the underlying `./scripts/build-electron.sh` script:
|
||||
|
||||
```bash
|
||||
# Direct script usage examples
|
||||
./scripts/build-electron.sh --dev # Development build
|
||||
./scripts/build-electron.sh --test # Test build
|
||||
./scripts/build-electron.sh --prod # Production build
|
||||
./scripts/build-electron.sh --prod --windows # Windows production
|
||||
./scripts/build-electron.sh --test --appimage # Linux AppImage test
|
||||
./scripts/build-electron.sh --dev --mac # macOS development
|
||||
./scripts/build-electron.sh --prod --dmg # macOS DMG production
|
||||
```
|
||||
|
||||
#### Utility Scripts
|
||||
|
||||
```bash
|
||||
# Cleanup scripts
|
||||
npm run clean:electron # Clean Electron build artifacts
|
||||
|
||||
# Development scripts
|
||||
npm run electron:dev # Start development server
|
||||
npm run electron:dev-full # Full development workflow
|
||||
npm run electron:setup # Setup Electron environment
|
||||
```
|
||||
|
||||
### Build Output Structure
|
||||
|
||||
#### Development Build
|
||||
|
||||
```
|
||||
electron/
|
||||
├── app/ # Web assets
|
||||
├── build/ # Compiled TypeScript
|
||||
├── dist/ # Build artifacts (empty in dev)
|
||||
└── node_modules/ # Dependencies
|
||||
```
|
||||
|
||||
#### Production Build
|
||||
|
||||
```
|
||||
electron/
|
||||
├── app/ # Web assets
|
||||
├── build/ # Compiled TypeScript
|
||||
├── dist/ # Distribution packages
|
||||
│ ├── TimeSafari.exe # Windows executable
|
||||
│ ├── TimeSafari.dmg # macOS installer
|
||||
│ ├── TimeSafari.AppImage # Linux AppImage
|
||||
│ └── TimeSafari.deb # Debian package
|
||||
└── node_modules/ # Dependencies
|
||||
```
|
||||
|
||||
### Code Signing and Notarization
|
||||
|
||||
#### macOS Code Signing
|
||||
|
||||
For public distribution on macOS, you need to code sign and notarize your app:
|
||||
|
||||
@@ -265,51 +584,131 @@ For public distribution on macOS, you need to code sign and notarize your app:
|
||||
|
||||
2. Build with signing:
|
||||
```bash
|
||||
npm run electron:build-mac
|
||||
npm run build:electron:mac:prod
|
||||
```
|
||||
|
||||
#### Windows Code Signing
|
||||
|
||||
For Windows distribution, configure Authenticode signing:
|
||||
|
||||
1. Set up environment variables:
|
||||
```bash
|
||||
export CSC_LINK=/path/to/your/certificate.p12
|
||||
export CSC_KEY_PASSWORD=your_certificate_password
|
||||
```
|
||||
|
||||
2. Build with signing:
|
||||
```bash
|
||||
npm run build:electron:windows:prod
|
||||
```
|
||||
|
||||
### Running the Packaged App
|
||||
|
||||
- **Linux**:
|
||||
- AppImage: Make executable and run
|
||||
```bash
|
||||
chmod +x dist-electron-packages/TimeSafari-*.AppImage
|
||||
./dist-electron-packages/TimeSafari-*.AppImage
|
||||
```
|
||||
- DEB: Install and run
|
||||
```bash
|
||||
sudo dpkg -i dist-electron-packages/timesafari_*_amd64.deb
|
||||
timesafari
|
||||
```
|
||||
#### Linux
|
||||
|
||||
- **macOS**:
|
||||
- `.app` bundle: Double-click `TimeSafari.app` in Finder
|
||||
- `.dmg` installer:
|
||||
1. Double-click the `.dmg` file
|
||||
2. Drag the app to your Applications folder
|
||||
3. Launch from Applications
|
||||
- `.zip` archive:
|
||||
1. Extract the `.zip` file
|
||||
2. Move `TimeSafari.app` to your Applications folder
|
||||
3. Launch from Applications
|
||||
- **AppImage**: Make executable and run
|
||||
```bash
|
||||
chmod +x electron/dist/TimeSafari-*.AppImage
|
||||
./electron/dist/TimeSafari-*.AppImage
|
||||
```
|
||||
|
||||
Note: If you get a security warning when running the app:
|
||||
1. Right-click the app
|
||||
2. Select "Open"
|
||||
3. Click "Open" in the security dialog
|
||||
- **DEB**: Install and run
|
||||
```bash
|
||||
sudo dpkg -i electron/dist/timesafari_*_amd64.deb
|
||||
timesafari
|
||||
```
|
||||
|
||||
### Development Testing
|
||||
#### macOS
|
||||
|
||||
For testing the Electron build before packaging:
|
||||
- **`.app` bundle**: Double-click `TimeSafari.app` in Finder
|
||||
- **`.dmg` installer**:
|
||||
1. Double-click the `.dmg` file
|
||||
2. Drag the app to your Applications folder
|
||||
3. Launch from Applications
|
||||
|
||||
Note: If you get a security warning when running the app:
|
||||
1. Right-click the app
|
||||
2. Select "Open"
|
||||
3. Click "Open" in the security dialog
|
||||
|
||||
#### Windows
|
||||
|
||||
- **NSIS installer**: Run the `.exe` installer and follow the setup wizard
|
||||
- **Portable**: Extract and run the portable executable
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
#### Common Build Issues
|
||||
|
||||
**TypeScript Compilation Errors**:
|
||||
```bash
|
||||
# Build and run in development mode (includes DevTools)
|
||||
npm run electron:dev
|
||||
|
||||
# Build in production mode and test
|
||||
npm run build:electron-prod && npm run electron:start
|
||||
# Clean and rebuild
|
||||
npm run clean:electron
|
||||
cd electron && npm run build
|
||||
```
|
||||
|
||||
**Native Module Issues**:
|
||||
```bash
|
||||
# Rebuild native modules
|
||||
cd electron && npm run build
|
||||
```
|
||||
|
||||
**Asset Copy Issues**:
|
||||
```bash
|
||||
# Verify Capacitor sync
|
||||
npx cap sync electron
|
||||
```
|
||||
|
||||
#### Platform-Specific Issues
|
||||
|
||||
**Windows**:
|
||||
- Ensure Windows Build Tools installed
|
||||
- Check NSIS installation
|
||||
- Verify code signing certificates
|
||||
|
||||
**macOS**:
|
||||
- Install Xcode Command Line Tools
|
||||
- Configure code signing certificates
|
||||
- Check app notarization requirements
|
||||
|
||||
**Linux**:
|
||||
- Install required packages (rpm-tools, etc.)
|
||||
- Check AppImage dependencies
|
||||
- Verify desktop integration
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
#### Build Performance
|
||||
|
||||
- Use concurrent TypeScript compilation
|
||||
- Optimize asset copying
|
||||
- Minimize file system operations
|
||||
- Cache node_modules between builds
|
||||
|
||||
#### Runtime Performance
|
||||
|
||||
- Optimize main process initialization
|
||||
- Minimize startup dependencies
|
||||
- Use lazy loading for features
|
||||
- Monitor memory usage and implement proper cleanup
|
||||
|
||||
### Security Considerations
|
||||
|
||||
#### Production Builds
|
||||
|
||||
- Disable developer tools
|
||||
- Remove debug information
|
||||
- Enable security policies
|
||||
- Implement sandboxing
|
||||
|
||||
#### Update Security
|
||||
|
||||
- Secure update channels
|
||||
- Package integrity verification
|
||||
- Rollback capabilities
|
||||
|
||||
For detailed documentation, see [docs/electron-build-patterns.md](docs/electron-build-patterns.md).
|
||||
|
||||
## Mobile Builds (Capacitor)
|
||||
|
||||
### iOS Build
|
||||
|
||||
594
docs/electron-build-patterns.md
Normal file
594
docs/electron-build-patterns.md
Normal file
@@ -0,0 +1,594 @@
|
||||
# Electron Build Patterns
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-01-27
|
||||
**Status**: 🎯 **ACTIVE** - Current Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
TimeSafari's Electron build system provides comprehensive packaging and
|
||||
distribution capabilities across Windows, macOS, and Linux platforms. The
|
||||
system supports multiple build modes, environment configurations, and
|
||||
package formats for different deployment scenarios.
|
||||
|
||||
## Build Architecture
|
||||
|
||||
### Multi-Stage Build Process
|
||||
|
||||
```
|
||||
1. Web Build (Vite) → 2. Capacitor Sync → 3. TypeScript Compile → 4. Package
|
||||
```
|
||||
|
||||
**Stage 1: Web Build**
|
||||
- Vite builds web assets with Electron-specific configuration
|
||||
- Environment variables loaded based on build mode
|
||||
- Assets optimized for desktop application
|
||||
|
||||
**Stage 2: Capacitor Sync**
|
||||
- Copies web assets to Electron app directory
|
||||
- Syncs Capacitor configuration and plugins
|
||||
- Prepares native module bindings
|
||||
|
||||
**Stage 3: TypeScript Compile**
|
||||
- Compiles Electron main process TypeScript
|
||||
- Rebuilds native modules for target platform
|
||||
- Generates production-ready JavaScript
|
||||
|
||||
**Stage 4: Package Creation**
|
||||
- Creates platform-specific installers
|
||||
- Generates distribution packages
|
||||
- Signs applications (when configured)
|
||||
|
||||
## Build Modes
|
||||
|
||||
### Development Mode (--mode development)
|
||||
|
||||
**Purpose**: Local development and testing
|
||||
**Configuration**: Development environment variables
|
||||
**Output**: Unpacked application for testing
|
||||
|
||||
```bash
|
||||
# Development build (runs app)
|
||||
npm run build:electron:dev
|
||||
|
||||
# Development build with explicit mode
|
||||
npm run build:electron -- --mode development
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Hot reload enabled
|
||||
- Debug tools available
|
||||
- Development logging
|
||||
- Unoptimized assets
|
||||
|
||||
### Testing Mode (--mode test)
|
||||
|
||||
**Purpose**: Staging and testing environments
|
||||
**Configuration**: Test environment variables
|
||||
**Output**: Packaged application for testing
|
||||
|
||||
```bash
|
||||
# Test build
|
||||
npm run build:electron -- --mode test
|
||||
|
||||
# Test build with specific platform
|
||||
npm run build:electron:windows -- --mode test
|
||||
npm run build:electron:mac -- --mode test
|
||||
npm run build:electron:linux -- --mode test
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Test API endpoints
|
||||
- Staging configurations
|
||||
- Optimized for testing
|
||||
- Debug information available
|
||||
|
||||
### Production Mode (--mode production)
|
||||
|
||||
**Purpose**: Production deployment
|
||||
**Configuration**: Production environment variables
|
||||
**Output**: Optimized distribution packages
|
||||
|
||||
```bash
|
||||
# Production build
|
||||
npm run build:electron -- --mode production
|
||||
|
||||
# Production build with specific platform
|
||||
npm run build:electron:windows -- --mode production
|
||||
npm run build:electron:mac -- --mode production
|
||||
npm run build:electron:linux -- --mode production
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Production optimizations
|
||||
- Code minification
|
||||
- Security hardening
|
||||
- Performance optimizations
|
||||
|
||||
## Platform-Specific Builds
|
||||
|
||||
### Windows Builds
|
||||
|
||||
**Target Platforms**: Windows 10/11 (x64)
|
||||
**Package Formats**: NSIS installer, portable executable
|
||||
|
||||
```bash
|
||||
# Windows development build
|
||||
npm run build:electron:windows -- --mode development
|
||||
|
||||
# Windows test build
|
||||
npm run build:electron:windows -- --mode test
|
||||
|
||||
# Windows production build
|
||||
npm run build:electron:windows -- --mode production
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- NSIS installer with custom options
|
||||
- Desktop and Start Menu shortcuts
|
||||
- Elevation permissions for installation
|
||||
- Custom installation directory support
|
||||
|
||||
### macOS Builds
|
||||
|
||||
**Target Platforms**: macOS 10.15+ (x64, arm64)
|
||||
**Package Formats**: DMG installer, app bundle
|
||||
|
||||
```bash
|
||||
# macOS development build
|
||||
npm run build:electron:mac -- --mode development
|
||||
|
||||
# macOS test build
|
||||
npm run build:electron:mac -- --mode test
|
||||
|
||||
# macOS production build
|
||||
npm run build:electron:mac -- --mode production
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- Universal binary (x64 + arm64)
|
||||
- DMG installer with custom branding
|
||||
- App Store compliance (when configured)
|
||||
- Code signing support
|
||||
|
||||
### Linux Builds
|
||||
|
||||
**Target Platforms**: Ubuntu 18.04+, Debian 10+, Arch Linux
|
||||
**Package Formats**: AppImage, DEB, RPM
|
||||
|
||||
```bash
|
||||
# Linux development build
|
||||
npm run build:electron:linux -- --mode development
|
||||
|
||||
# Linux test build
|
||||
npm run build:electron:linux -- --mode test
|
||||
|
||||
# Linux production build
|
||||
npm run build:electron:linux -- --mode production
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- AppImage for universal distribution
|
||||
- DEB package for Debian-based systems
|
||||
- RPM package for Red Hat-based systems
|
||||
- Desktop integration
|
||||
|
||||
## Package-Specific Builds
|
||||
|
||||
### AppImage Package
|
||||
|
||||
**Format**: Self-contained Linux executable
|
||||
**Distribution**: Universal Linux distribution
|
||||
|
||||
```bash
|
||||
# AppImage development build
|
||||
npm run build:electron:appimage -- --mode development
|
||||
|
||||
# AppImage test build
|
||||
npm run build:electron:appimage -- --mode test
|
||||
|
||||
# AppImage production build
|
||||
npm run build:electron:appimage -- --mode production
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Single file distribution
|
||||
- No installation required
|
||||
- Portable across Linux distributions
|
||||
- Automatic updates support
|
||||
|
||||
### DEB Package
|
||||
|
||||
**Format**: Debian package installer
|
||||
**Distribution**: Debian-based Linux systems
|
||||
|
||||
```bash
|
||||
# DEB development build
|
||||
npm run build:electron:deb -- --mode development
|
||||
|
||||
# DEB test build
|
||||
npm run build:electron:deb -- --mode test
|
||||
|
||||
# DEB production build
|
||||
npm run build:electron:deb -- --mode production
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Native package management
|
||||
- Dependency resolution
|
||||
- System integration
|
||||
- Easy installation/uninstallation
|
||||
|
||||
### DMG Package
|
||||
|
||||
**Format**: macOS disk image
|
||||
**Distribution**: macOS systems
|
||||
|
||||
```bash
|
||||
# DMG development build
|
||||
npm run build:electron:dmg -- --mode development
|
||||
|
||||
# DMG test build
|
||||
npm run build:electron:dmg -- --mode test
|
||||
|
||||
# DMG production build
|
||||
npm run build:electron:dmg -- --mode production
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Native macOS installer
|
||||
- Custom branding and layout
|
||||
- Drag-and-drop installation
|
||||
- Code signing support
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
**Development Environment**:
|
||||
```bash
|
||||
VITE_API_URL=http://localhost:3000
|
||||
VITE_DEBUG=true
|
||||
VITE_LOG_LEVEL=debug
|
||||
VITE_ENABLE_DEV_TOOLS=true
|
||||
```
|
||||
|
||||
**Testing Environment**:
|
||||
```bash
|
||||
VITE_API_URL=https://test-api.timesafari.com
|
||||
VITE_DEBUG=false
|
||||
VITE_LOG_LEVEL=info
|
||||
VITE_ENABLE_DEV_TOOLS=false
|
||||
```
|
||||
|
||||
**Production Environment**:
|
||||
```bash
|
||||
VITE_API_URL=https://api.timesafari.com
|
||||
VITE_DEBUG=false
|
||||
VITE_LOG_LEVEL=warn
|
||||
VITE_ENABLE_DEV_TOOLS=false
|
||||
```
|
||||
|
||||
### Build Configuration
|
||||
|
||||
**Vite Configuration** (`vite.config.electron.mts`):
|
||||
```typescript
|
||||
export default defineConfig(({ mode }) => {
|
||||
const env = loadEnv(mode, process.cwd(), '');
|
||||
|
||||
return {
|
||||
mode,
|
||||
build: {
|
||||
outDir: 'dist',
|
||||
emptyOutDir: true,
|
||||
sourcemap: mode === 'development',
|
||||
minify: mode === 'production'
|
||||
},
|
||||
define: {
|
||||
__DEV__: mode === 'development',
|
||||
__TEST__: mode === 'test',
|
||||
__PROD__: mode === 'production'
|
||||
}
|
||||
};
|
||||
});
|
||||
```
|
||||
|
||||
**Electron Builder Configuration** (`electron-builder.config.json`):
|
||||
```json
|
||||
{
|
||||
"appId": "app.timesafari.desktop",
|
||||
"productName": "TimeSafari",
|
||||
"directories": {
|
||||
"buildResources": "resources",
|
||||
"output": "dist"
|
||||
},
|
||||
"files": [
|
||||
"assets/**/*",
|
||||
"build/**/*",
|
||||
"capacitor.config.*",
|
||||
"app/**/*"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Build Scripts Reference
|
||||
|
||||
### Main Build Scripts
|
||||
|
||||
```bash
|
||||
# Development builds
|
||||
npm run build:electron:dev # Development build and run
|
||||
npm run build:electron --dev # Development build only
|
||||
|
||||
# Testing builds
|
||||
npm run build:electron:test # Test environment build
|
||||
|
||||
# Production builds
|
||||
npm run build:electron:prod # Production environment build
|
||||
```
|
||||
|
||||
### Platform-Specific Scripts
|
||||
|
||||
```bash
|
||||
# Windows builds
|
||||
npm run build:electron:windows # Windows production build
|
||||
npm run build:electron:windows:dev # Windows development build
|
||||
npm run build:electron:windows:test # Windows test build
|
||||
npm run build:electron:windows:prod # Windows production build
|
||||
|
||||
# macOS builds
|
||||
npm run build:electron:mac # macOS production build
|
||||
npm run build:electron:mac:dev # macOS development build
|
||||
npm run build:electron:mac:test # macOS test build
|
||||
npm run build:electron:mac:prod # macOS production build
|
||||
|
||||
# Linux builds
|
||||
npm run build:electron:linux # Linux production build
|
||||
npm run build:electron:linux:dev # Linux development build
|
||||
npm run build:electron:linux:test # Linux test build
|
||||
npm run build:electron:linux:prod # Linux production build
|
||||
```
|
||||
|
||||
### Package-Specific Scripts
|
||||
|
||||
```bash
|
||||
# AppImage builds
|
||||
npm run build:electron:appimage # Linux AppImage production build
|
||||
npm run build:electron:appimage:dev # AppImage development build
|
||||
npm run build:electron:appimage:test # AppImage test build
|
||||
npm run build:electron:appimage:prod # AppImage production build
|
||||
|
||||
# DEB builds
|
||||
npm run build:electron:deb # Debian package production build
|
||||
npm run build:electron:deb:dev # DEB development build
|
||||
npm run build:electron:deb:test # DEB test build
|
||||
npm run build:electron:deb:prod # DEB production build
|
||||
|
||||
# DMG builds
|
||||
npm run build:electron:dmg # macOS DMG production build
|
||||
npm run build:electron:dmg:dev # DMG development build
|
||||
npm run build:electron:dmg:test # DMG test build
|
||||
npm run build:electron:dmg:prod # DMG production build
|
||||
```
|
||||
|
||||
### Direct Script Usage
|
||||
|
||||
All npm scripts use the underlying `./scripts/build-electron.sh` script:
|
||||
|
||||
```bash
|
||||
# Direct script usage examples
|
||||
./scripts/build-electron.sh --dev # Development build
|
||||
./scripts/build-electron.sh --test # Test build
|
||||
./scripts/build-electron.sh --prod # Production build
|
||||
./scripts/build-electron.sh --prod --windows # Windows production
|
||||
./scripts/build-electron.sh --test --appimage # Linux AppImage test
|
||||
./scripts/build-electron.sh --dev --mac # macOS development
|
||||
./scripts/build-electron.sh --prod --dmg # macOS DMG production
|
||||
```
|
||||
|
||||
### Utility Scripts
|
||||
|
||||
```bash
|
||||
# Cleanup scripts
|
||||
npm run clean:electron # Clean Electron build artifacts
|
||||
|
||||
# Development scripts
|
||||
npm run electron:dev # Start development server
|
||||
npm run electron:dev-full # Full development workflow
|
||||
```
|
||||
|
||||
## Build Output Structure
|
||||
|
||||
### Development Build
|
||||
|
||||
```
|
||||
electron/
|
||||
├── app/ # Web assets
|
||||
├── build/ # Compiled TypeScript
|
||||
├── dist/ # Build artifacts (empty in dev)
|
||||
└── node_modules/ # Dependencies
|
||||
```
|
||||
|
||||
### Production Build
|
||||
|
||||
```
|
||||
electron/
|
||||
├── app/ # Web assets
|
||||
├── build/ # Compiled TypeScript
|
||||
├── dist/ # Distribution packages
|
||||
│ ├── TimeSafari.exe # Windows executable
|
||||
│ ├── TimeSafari.dmg # macOS installer
|
||||
│ ├── TimeSafari.AppImage # Linux AppImage
|
||||
│ └── TimeSafari.deb # Debian package
|
||||
└── node_modules/ # Dependencies
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Build Issues
|
||||
|
||||
**TypeScript Compilation Errors**:
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
npm run clean:electron
|
||||
cd electron && npm run build
|
||||
```
|
||||
|
||||
**Native Module Issues**:
|
||||
```bash
|
||||
# Rebuild native modules
|
||||
cd electron && npm run build
|
||||
```
|
||||
|
||||
**Asset Copy Issues**:
|
||||
```bash
|
||||
# Verify Capacitor sync
|
||||
npx cap sync electron
|
||||
```
|
||||
|
||||
**Package Creation Failures**:
|
||||
```bash
|
||||
# Check electron-builder configuration
|
||||
# Verify platform-specific requirements
|
||||
# Check signing certificates (macOS/Windows)
|
||||
```
|
||||
|
||||
### Platform-Specific Issues
|
||||
|
||||
**Windows**:
|
||||
- Ensure Windows Build Tools installed
|
||||
- Check NSIS installation
|
||||
- Verify code signing certificates
|
||||
|
||||
**macOS**:
|
||||
- Install Xcode Command Line Tools
|
||||
- Configure code signing certificates
|
||||
- Check app notarization requirements
|
||||
|
||||
**Linux**:
|
||||
- Install required packages (rpm-tools, etc.)
|
||||
- Check AppImage dependencies
|
||||
- Verify desktop integration
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Build Performance
|
||||
|
||||
**Parallel Builds**:
|
||||
- Use concurrent TypeScript compilation
|
||||
- Optimize asset copying
|
||||
- Minimize file system operations
|
||||
|
||||
**Caching Strategies**:
|
||||
- Cache node_modules between builds
|
||||
- Cache compiled TypeScript
|
||||
- Cache web assets when unchanged
|
||||
|
||||
### Runtime Performance
|
||||
|
||||
**Application Startup**:
|
||||
- Optimize main process initialization
|
||||
- Minimize startup dependencies
|
||||
- Use lazy loading for features
|
||||
|
||||
**Memory Management**:
|
||||
- Monitor memory usage
|
||||
- Implement proper cleanup
|
||||
- Optimize asset loading
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Code Signing
|
||||
|
||||
**Windows**:
|
||||
- Authenticode code signing
|
||||
- EV certificate for SmartScreen
|
||||
- Timestamp server configuration
|
||||
|
||||
**macOS**:
|
||||
- Developer ID code signing
|
||||
- App notarization
|
||||
- Hardened runtime
|
||||
|
||||
**Linux**:
|
||||
- GPG signing for packages
|
||||
- AppImage signing
|
||||
- Package verification
|
||||
|
||||
### Security Hardening
|
||||
|
||||
**Production Builds**:
|
||||
- Disable developer tools
|
||||
- Remove debug information
|
||||
- Enable security policies
|
||||
- Implement sandboxing
|
||||
|
||||
**Update Security**:
|
||||
- Secure update channels
|
||||
- Package integrity verification
|
||||
- Rollback capabilities
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
# Example workflow for Electron builds
|
||||
- name: Build Electron
|
||||
run: |
|
||||
npm run build:electron -- --mode production
|
||||
npm run build:electron:windows -- --mode production
|
||||
npm run build:electron:mac -- --mode production
|
||||
npm run build:electron:linux -- --mode production
|
||||
```
|
||||
|
||||
### Automated Testing
|
||||
|
||||
```yaml
|
||||
# Test Electron builds
|
||||
- name: Test Electron
|
||||
run: |
|
||||
npm run build:electron -- --mode test
|
||||
# Run automated tests
|
||||
```
|
||||
|
||||
### Release Management
|
||||
|
||||
```yaml
|
||||
# Create releases with assets
|
||||
- name: Create Release
|
||||
run: |
|
||||
# Upload built packages
|
||||
# Create GitHub release
|
||||
# Publish to distribution channels
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. **Use development mode for local testing**
|
||||
2. **Test builds in all environments**
|
||||
3. **Validate packages before distribution**
|
||||
4. **Maintain consistent versioning**
|
||||
|
||||
### Build Optimization
|
||||
|
||||
1. **Minimize build dependencies**
|
||||
2. **Use efficient asset processing**
|
||||
3. **Implement proper caching**
|
||||
4. **Optimize for target platforms**
|
||||
|
||||
### Quality Assurance
|
||||
|
||||
1. **Test on all target platforms**
|
||||
2. **Validate installation processes**
|
||||
3. **Check update mechanisms**
|
||||
4. **Verify security configurations**
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active implementation
|
||||
**Last Updated**: 2025-01-27
|
||||
**Version**: 1.0
|
||||
**Maintainer**: Matthew Raymer
|
||||
499
electron/README.md
Normal file
499
electron/README.md
Normal file
@@ -0,0 +1,499 @@
|
||||
# TimeSafari Electron Build System
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-01-27
|
||||
**Status**: 🎯 **ACTIVE** - Production Ready
|
||||
|
||||
## Overview
|
||||
|
||||
TimeSafari's Electron build system provides comprehensive desktop application
|
||||
packaging and distribution capabilities. The system supports multiple platforms,
|
||||
build modes, and package formats for different deployment scenarios.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Development Build
|
||||
|
||||
```bash
|
||||
# Start development build (runs app)
|
||||
npm run build:electron:dev
|
||||
|
||||
# Development build only
|
||||
npm run build:electron -- --mode development
|
||||
```
|
||||
|
||||
### Production Build
|
||||
|
||||
```bash
|
||||
# Production build for all platforms
|
||||
npm run build:electron:prod
|
||||
|
||||
# Platform-specific production builds
|
||||
npm run build:electron:windows:prod
|
||||
npm run build:electron:mac:prod
|
||||
npm run build:electron:linux:prod
|
||||
```
|
||||
|
||||
### Package-Specific Builds
|
||||
|
||||
```bash
|
||||
# AppImage for Linux
|
||||
npm run build:electron:appimage:prod
|
||||
|
||||
# DEB package for Debian/Ubuntu
|
||||
npm run build:electron:deb:prod
|
||||
|
||||
# DMG for macOS
|
||||
npm run build:electron:dmg:prod
|
||||
```
|
||||
|
||||
## Build Architecture
|
||||
|
||||
### Multi-Stage Process
|
||||
|
||||
```
|
||||
1. Web Build (Vite) → 2. Capacitor Sync → 3. TypeScript Compile → 4. Package
|
||||
```
|
||||
|
||||
**Stage 1: Web Build**
|
||||
- Vite builds web assets with Electron configuration
|
||||
- Environment variables loaded based on build mode
|
||||
- Assets optimized for desktop application
|
||||
|
||||
**Stage 2: Capacitor Sync**
|
||||
- Copies web assets to Electron app directory
|
||||
- Syncs Capacitor configuration and plugins
|
||||
- Prepares native module bindings
|
||||
|
||||
**Stage 3: TypeScript Compile**
|
||||
- Compiles Electron main process TypeScript
|
||||
- Rebuilds native modules for target platform
|
||||
- Generates production-ready JavaScript
|
||||
|
||||
**Stage 4: Package Creation**
|
||||
- Creates platform-specific installers
|
||||
- Generates distribution packages
|
||||
- Signs applications (when configured)
|
||||
|
||||
## Build Modes
|
||||
|
||||
### Development Mode
|
||||
|
||||
**Purpose**: Local development and testing
|
||||
**Command**: `npm run build:electron:dev`
|
||||
**Features**:
|
||||
- Hot reload enabled
|
||||
- Debug tools available
|
||||
- Development logging
|
||||
- Unoptimized assets
|
||||
|
||||
### Testing Mode
|
||||
|
||||
**Purpose**: Staging and testing environments
|
||||
**Command**: `npm run build:electron -- --mode test`
|
||||
**Features**:
|
||||
- Test API endpoints
|
||||
- Staging configurations
|
||||
- Optimized for testing
|
||||
- Debug information available
|
||||
|
||||
### Production Mode
|
||||
|
||||
**Purpose**: Production deployment
|
||||
**Command**: `npm run build:electron -- --mode production`
|
||||
**Features**:
|
||||
- Production optimizations
|
||||
- Code minification
|
||||
- Security hardening
|
||||
- Performance optimizations
|
||||
|
||||
## Platform Support
|
||||
|
||||
### Windows
|
||||
|
||||
**Target**: Windows 10/11 (x64)
|
||||
**Package**: NSIS installer
|
||||
**Command**: `npm run build:electron:windows:prod`
|
||||
|
||||
**Features**:
|
||||
- NSIS installer with custom options
|
||||
- Desktop and Start Menu shortcuts
|
||||
- Elevation permissions for installation
|
||||
- Custom installation directory support
|
||||
|
||||
### macOS
|
||||
|
||||
**Target**: macOS 10.15+ (x64, arm64)
|
||||
**Package**: DMG installer, app bundle
|
||||
**Command**: `npm run build:electron:mac:prod`
|
||||
|
||||
**Features**:
|
||||
- Universal binary (x64 + arm64)
|
||||
- DMG installer with custom branding
|
||||
- App Store compliance (when configured)
|
||||
- Code signing support
|
||||
|
||||
### Linux
|
||||
|
||||
**Target**: Ubuntu 18.04+, Debian 10+, Arch Linux
|
||||
**Package**: AppImage, DEB, RPM
|
||||
**Command**: `npm run build:electron:linux:prod`
|
||||
|
||||
**Features**:
|
||||
- AppImage for universal distribution
|
||||
- DEB package for Debian-based systems
|
||||
- RPM package for Red Hat-based systems
|
||||
- Desktop integration
|
||||
|
||||
## Package Formats
|
||||
|
||||
### AppImage
|
||||
|
||||
**Format**: Self-contained Linux executable
|
||||
**Command**: `npm run build:electron:appimage:prod`
|
||||
**Features**:
|
||||
- Single file distribution
|
||||
- No installation required
|
||||
- Portable across Linux distributions
|
||||
- Automatic updates support
|
||||
|
||||
### DEB Package
|
||||
|
||||
**Format**: Debian package installer
|
||||
**Command**: `npm run build:electron:deb:prod`
|
||||
**Features**:
|
||||
- Native package management
|
||||
- Dependency resolution
|
||||
- System integration
|
||||
- Easy installation/uninstallation
|
||||
|
||||
### DMG Package
|
||||
|
||||
**Format**: macOS disk image
|
||||
**Command**: `npm run build:electron:dmg:prod`
|
||||
**Features**:
|
||||
- Native macOS installer
|
||||
- Custom branding and layout
|
||||
- Drag-and-drop installation
|
||||
- Code signing support
|
||||
|
||||
## Build Scripts Reference
|
||||
|
||||
### Main Build Scripts
|
||||
|
||||
```bash
|
||||
# Development builds
|
||||
npm run build:electron:dev # Development build and run
|
||||
npm run build:electron -- --mode dev # Development build only
|
||||
|
||||
# Testing builds
|
||||
npm run build:electron -- --mode test # Test environment build
|
||||
|
||||
# Production builds
|
||||
npm run build:electron -- --mode prod # Production environment build
|
||||
```
|
||||
|
||||
### Platform-Specific Scripts
|
||||
|
||||
```bash
|
||||
# Windows builds
|
||||
npm run build:electron:windows # Windows executable
|
||||
npm run build:electron:windows:dev # Windows development
|
||||
npm run build:electron:windows:test # Windows test
|
||||
npm run build:electron:windows:prod # Windows production
|
||||
|
||||
# macOS builds
|
||||
npm run build:electron:mac # macOS app bundle
|
||||
npm run build:electron:mac:dev # macOS development
|
||||
npm run build:electron:mac:test # macOS test
|
||||
npm run build:electron:mac:prod # macOS production
|
||||
|
||||
# Linux builds
|
||||
npm run build:electron:linux # Linux executable
|
||||
npm run build:electron:linux:dev # Linux development
|
||||
npm run build:electron:linux:test # Linux test
|
||||
npm run build:electron:linux:prod # Linux production
|
||||
```
|
||||
|
||||
### Package-Specific Scripts
|
||||
|
||||
```bash
|
||||
# AppImage builds
|
||||
npm run build:electron:appimage # Linux AppImage
|
||||
npm run build:electron:appimage:dev # AppImage development
|
||||
npm run build:electron:appimage:test # AppImage test
|
||||
npm run build:electron:appimage:prod # AppImage production
|
||||
|
||||
# DEB builds
|
||||
npm run build:electron:deb # Debian package
|
||||
npm run build:electron:deb:dev # DEB development
|
||||
npm run build:electron:deb:test # DEB test
|
||||
npm run build:electron:deb:prod # DEB production
|
||||
|
||||
# DMG builds
|
||||
npm run build:electron:dmg # macOS DMG
|
||||
npm run build:electron:dmg:dev # DMG development
|
||||
npm run build:electron:dmg:test # DMG test
|
||||
npm run build:electron:dmg:prod # DMG production
|
||||
```
|
||||
|
||||
### Utility Scripts
|
||||
|
||||
```bash
|
||||
# Cleanup scripts
|
||||
npm run clean:electron # Clean Electron build artifacts
|
||||
|
||||
# Development scripts
|
||||
npm run electron:dev # Start development server
|
||||
npm run electron:dev-full # Full development workflow
|
||||
npm run electron:setup # Setup Electron environment
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### electron-builder.config.json
|
||||
|
||||
Main configuration for Electron Builder:
|
||||
|
||||
```json
|
||||
{
|
||||
"appId": "app.timesafari.desktop",
|
||||
"productName": "TimeSafari",
|
||||
"directories": {
|
||||
"buildResources": "resources",
|
||||
"output": "dist"
|
||||
},
|
||||
"files": [
|
||||
"assets/**/*",
|
||||
"build/**/*",
|
||||
"capacitor.config.*",
|
||||
"app/**/*"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### package.json Scripts
|
||||
|
||||
Local Electron scripts for building:
|
||||
|
||||
```json
|
||||
{
|
||||
"build": "tsc && electron-rebuild",
|
||||
"build:windows": "npm run build && electron-builder build --win",
|
||||
"build:mac": "npm run build && electron-builder build --mac",
|
||||
"build:linux": "npm run build && electron-builder build --linux",
|
||||
"build:appimage": "npm run build && electron-builder build --linux AppImage",
|
||||
"build:deb": "npm run build && electron-builder build --linux deb",
|
||||
"build:dmg": "npm run build && electron-builder build --mac dmg"
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
**Development**:
|
||||
```bash
|
||||
VITE_API_URL=http://localhost:3000
|
||||
VITE_DEBUG=true
|
||||
VITE_LOG_LEVEL=debug
|
||||
VITE_ENABLE_DEV_TOOLS=true
|
||||
```
|
||||
|
||||
**Testing**:
|
||||
```bash
|
||||
VITE_API_URL=https://test-api.timesafari.com
|
||||
VITE_DEBUG=false
|
||||
VITE_LOG_LEVEL=info
|
||||
VITE_ENABLE_DEV_TOOLS=false
|
||||
```
|
||||
|
||||
**Production**:
|
||||
```bash
|
||||
VITE_API_URL=https://api.timesafari.com
|
||||
VITE_DEBUG=false
|
||||
VITE_LOG_LEVEL=warn
|
||||
VITE_ENABLE_DEV_TOOLS=false
|
||||
```
|
||||
|
||||
## Build Output Structure
|
||||
|
||||
### Development Build
|
||||
|
||||
```
|
||||
electron/
|
||||
├── app/ # Web assets
|
||||
├── build/ # Compiled TypeScript
|
||||
├── dist/ # Build artifacts (empty in dev)
|
||||
└── node_modules/ # Dependencies
|
||||
```
|
||||
|
||||
### Production Build
|
||||
|
||||
```
|
||||
electron/
|
||||
├── app/ # Web assets
|
||||
├── build/ # Compiled TypeScript
|
||||
├── dist/ # Distribution packages
|
||||
│ ├── TimeSafari.exe # Windows executable
|
||||
│ ├── TimeSafari.dmg # macOS installer
|
||||
│ ├── TimeSafari.AppImage # Linux AppImage
|
||||
│ └── TimeSafari.deb # Debian package
|
||||
└── node_modules/ # Dependencies
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**TypeScript Compilation Errors**:
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
npm run clean:electron
|
||||
cd electron && npm run build
|
||||
```
|
||||
|
||||
**Native Module Issues**:
|
||||
```bash
|
||||
# Rebuild native modules
|
||||
cd electron && npm run build
|
||||
```
|
||||
|
||||
**Asset Copy Issues**:
|
||||
```bash
|
||||
# Verify Capacitor sync
|
||||
npx cap sync electron
|
||||
```
|
||||
|
||||
**Package Creation Failures**:
|
||||
```bash
|
||||
# Check electron-builder configuration
|
||||
# Verify platform-specific requirements
|
||||
# Check signing certificates (macOS/Windows)
|
||||
```
|
||||
|
||||
### Platform-Specific Issues
|
||||
|
||||
**Windows**:
|
||||
- Ensure Windows Build Tools installed
|
||||
- Check NSIS installation
|
||||
- Verify code signing certificates
|
||||
|
||||
**macOS**:
|
||||
- Install Xcode Command Line Tools
|
||||
- Configure code signing certificates
|
||||
- Check app notarization requirements
|
||||
|
||||
**Linux**:
|
||||
- Install required packages (rpm-tools, etc.)
|
||||
- Check AppImage dependencies
|
||||
- Verify desktop integration
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Build Performance
|
||||
|
||||
**Parallel Builds**:
|
||||
- Use concurrent TypeScript compilation
|
||||
- Optimize asset copying
|
||||
- Minimize file system operations
|
||||
|
||||
**Caching Strategies**:
|
||||
- Cache node_modules between builds
|
||||
- Cache compiled TypeScript
|
||||
- Cache web assets when unchanged
|
||||
|
||||
### Runtime Performance
|
||||
|
||||
**Application Startup**:
|
||||
- Optimize main process initialization
|
||||
- Minimize startup dependencies
|
||||
- Use lazy loading for features
|
||||
|
||||
**Memory Management**:
|
||||
- Monitor memory usage
|
||||
- Implement proper cleanup
|
||||
- Optimize asset loading
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Code Signing
|
||||
|
||||
**Windows**:
|
||||
- Authenticode code signing
|
||||
- EV certificate for SmartScreen
|
||||
- Timestamp server configuration
|
||||
|
||||
**macOS**:
|
||||
- Developer ID code signing
|
||||
- App notarization
|
||||
- Hardened runtime
|
||||
|
||||
**Linux**:
|
||||
- GPG signing for packages
|
||||
- AppImage signing
|
||||
- Package verification
|
||||
|
||||
### Security Hardening
|
||||
|
||||
**Production Builds**:
|
||||
- Disable developer tools
|
||||
- Remove debug information
|
||||
- Enable security policies
|
||||
- Implement sandboxing
|
||||
|
||||
**Update Security**:
|
||||
- Secure update channels
|
||||
- Package integrity verification
|
||||
- Rollback capabilities
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions Example
|
||||
|
||||
```yaml
|
||||
- name: Build Electron
|
||||
run: |
|
||||
npm run build:electron:windows:prod
|
||||
npm run build:electron:mac:prod
|
||||
npm run build:electron:linux:prod
|
||||
```
|
||||
|
||||
### Automated Testing
|
||||
|
||||
```yaml
|
||||
- name: Test Electron
|
||||
run: |
|
||||
npm run build:electron:test
|
||||
# Run automated tests
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. **Use development mode for local testing**
|
||||
2. **Test builds in all environments**
|
||||
3. **Validate packages before distribution**
|
||||
4. **Maintain consistent versioning**
|
||||
|
||||
### Build Optimization
|
||||
|
||||
1. **Minimize build dependencies**
|
||||
2. **Use efficient asset processing**
|
||||
3. **Implement proper caching**
|
||||
4. **Optimize for target platforms**
|
||||
|
||||
### Quality Assurance
|
||||
|
||||
1. **Test on all target platforms**
|
||||
2. **Validate installation processes**
|
||||
3. **Check update mechanisms**
|
||||
4. **Verify security configurations**
|
||||
|
||||
---
|
||||
|
||||
**Status**: Production ready
|
||||
**Last Updated**: 2025-01-27
|
||||
**Version**: 1.0
|
||||
**Maintainer**: Matthew Raymer
|
||||
@@ -18,7 +18,13 @@
|
||||
"electron:start-live": "node ./live-runner.js",
|
||||
"electron:start": "npm run build && electron --inspect=5858 ./",
|
||||
"electron:pack": "npm run build && electron-builder build --dir -c ./electron-builder.config.json",
|
||||
"electron:make": "npm run build && electron-builder build -c ./electron-builder.config.json -p always"
|
||||
"electron:make": "npm run build && electron-builder build -c ./electron-builder.config.json -p always",
|
||||
"build:windows": "npm run build && electron-builder build --win -c ./electron-builder.config.json",
|
||||
"build:mac": "npm run build && electron-builder build --mac -c ./electron-builder.config.json",
|
||||
"build:linux": "npm run build && electron-builder build --linux -c ./electron-builder.config.json",
|
||||
"build:appimage": "npm run build && electron-builder build --linux AppImage -c ./electron-builder.config.json",
|
||||
"build:deb": "npm run build && electron-builder build --linux deb -c ./electron-builder.config.json",
|
||||
"build:dmg": "npm run build && electron-builder build --mac dmg -c ./electron-builder.config.json"
|
||||
},
|
||||
"dependencies": {
|
||||
"@capacitor-community/electron": "^5.0.0",
|
||||
|
||||
42
package.json
42
package.json
@@ -9,7 +9,6 @@
|
||||
"lint": "eslint --ext .js,.ts,.vue --ignore-path .gitignore src",
|
||||
"lint-fix": "eslint --ext .js,.ts,.vue --ignore-path .gitignore --fix src",
|
||||
"prebuild": "eslint --ext .js,.ts,.vue --ignore-path .gitignore src && node sw_combine.js && node scripts/copy-wasm.js",
|
||||
"test:all": "./scripts/test-all.sh",
|
||||
"test:prerequisites": "node scripts/check-prerequisites.js",
|
||||
"test:web": "npx playwright test -c playwright.config-local.ts --trace on",
|
||||
"test:mobile": "./scripts/test-mobile.sh",
|
||||
@@ -31,21 +30,38 @@
|
||||
"docker:up:prod": "npm run build:web:build -- --mode production && docker-compose up production",
|
||||
"docker:down": "docker-compose down",
|
||||
"docker:logs": "docker-compose logs -f",
|
||||
"build:electron": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --mode electron --config vite.config.electron.mts",
|
||||
"electron:dev": "npm run build:electron && npx cap copy electron && cd electron && npm run electron:start",
|
||||
"electron:setup": "./scripts/setup-electron.sh",
|
||||
"electron:dev-full": "./scripts/electron-dev.sh",
|
||||
"electron:build": "npm run build:electron && npx cap copy electron && cd electron && ./build-packages.sh",
|
||||
"electron:build:appimage": "npm run build:electron && npx cap copy electron && cd electron && ./build-packages.sh appimage",
|
||||
"electron:build:deb": "npm run build:electron && npx cap copy electron && cd electron && ./build-packages.sh deb",
|
||||
"build:electron": "./scripts/build-electron.sh",
|
||||
"build:electron:dev": "./scripts/build-electron.sh --dev",
|
||||
"build:electron:test": "./scripts/build-electron.sh --test",
|
||||
"build:electron:prod": "./scripts/build-electron.sh --prod",
|
||||
"build:electron:windows": "./scripts/build-electron.sh --prod --windows",
|
||||
"build:electron:windows:dev": "./scripts/build-electron.sh --dev --windows",
|
||||
"build:electron:windows:test": "./scripts/build-electron.sh --test --windows",
|
||||
"build:electron:windows:prod": "./scripts/build-electron.sh --prod --windows",
|
||||
"build:electron:mac": "./scripts/build-electron.sh --prod --mac",
|
||||
"build:electron:mac:dev": "./scripts/build-electron.sh --dev --mac",
|
||||
"build:electron:mac:test": "./scripts/build-electron.sh --test --mac",
|
||||
"build:electron:mac:prod": "./scripts/build-electron.sh --prod --mac",
|
||||
"build:electron:linux": "./scripts/build-electron.sh --prod --linux",
|
||||
"build:electron:linux:dev": "./scripts/build-electron.sh --dev --linux",
|
||||
"build:electron:linux:test": "./scripts/build-electron.sh --test --linux",
|
||||
"build:electron:linux:prod": "./scripts/build-electron.sh --prod --linux",
|
||||
"build:electron:appimage": "./scripts/build-electron.sh --prod --appimage",
|
||||
"build:electron:appimage:dev": "./scripts/build-electron.sh --dev --appimage",
|
||||
"build:electron:appimage:test": "./scripts/build-electron.sh --test --appimage",
|
||||
"build:electron:appimage:prod": "./scripts/build-electron.sh --prod --appimage",
|
||||
"build:electron:deb": "./scripts/build-electron.sh --prod --deb",
|
||||
"build:electron:deb:dev": "./scripts/build-electron.sh --dev --deb",
|
||||
"build:electron:deb:test": "./scripts/build-electron.sh --test --deb",
|
||||
"build:electron:deb:prod": "./scripts/build-electron.sh --prod --deb",
|
||||
"build:electron:dmg": "./scripts/build-electron.sh --prod --dmg",
|
||||
"build:electron:dmg:dev": "./scripts/build-electron.sh --dev --dmg",
|
||||
"build:electron:dmg:test": "./scripts/build-electron.sh --test --dmg",
|
||||
"build:electron:dmg:prod": "./scripts/build-electron.sh --prod --dmg",
|
||||
"clean:android": "adb uninstall app.timesafari.app || true",
|
||||
"clean:electron": "rm -rf electron/app/* electron/dist/* || true",
|
||||
"clean:ios": "rm -rf ios/App/build ios/App/Pods ios/App/output ios/App/App/public ios/DerivedData ios/capacitor-cordova-ios-plugins ios/App/App/capacitor.config.json ios/App/App/config.xml || true",
|
||||
"clean:electron": "./scripts/build-electron.sh --clean",
|
||||
"build:android": "./scripts/build-android.sh",
|
||||
"build:electron:all": "./scripts/build-electron.sh",
|
||||
"build:electron:package": "./scripts/build-electron.sh --package",
|
||||
"build:electron:appimage": "./scripts/build-electron.sh --appimage",
|
||||
"build:electron:deb": "./scripts/build-electron.sh --deb",
|
||||
"fastlane:ios:beta": "cd ios && fastlane beta",
|
||||
"fastlane:ios:release": "cd ios && fastlane release",
|
||||
"fastlane:android:beta": "cd android && fastlane beta",
|
||||
|
||||
@@ -1,32 +1,36 @@
|
||||
#!/bin/bash
|
||||
# build-electron.sh
|
||||
# Author: Matthew Raymer
|
||||
# Description: Electron build script for TimeSafari application
|
||||
# This script handles the complete Electron build process including cleanup,
|
||||
# web build, Capacitor build, TypeScript compilation, and Electron packaging.
|
||||
# Description: Clean, modular Electron build script for TimeSafari application
|
||||
# This script handles Electron builds with proper separation of concerns and
|
||||
# no command chaining, following DRY principles.
|
||||
#
|
||||
# Usage:
|
||||
# ./scripts/build-electron.sh # Development build (runs app)
|
||||
# ./scripts/build-electron.sh --dev # Development build (runs app)
|
||||
# ./scripts/build-electron.sh --package # Package build (creates distributable)
|
||||
# ./scripts/build-electron.sh --appimage # Build AppImage package
|
||||
# ./scripts/build-electron.sh --deb # Build Debian package
|
||||
# ./scripts/build-electron.sh --test # Test environment build
|
||||
# ./scripts/build-electron.sh --prod # Production environment build
|
||||
# ./scripts/build-electron.sh --windows # Windows build
|
||||
# ./scripts/build-electron.sh --mac # macOS build
|
||||
# ./scripts/build-electron.sh --linux # Linux build
|
||||
# ./scripts/build-electron.sh --appimage # Linux AppImage
|
||||
# ./scripts/build-electron.sh --deb # Debian package
|
||||
# ./scripts/build-electron.sh --dmg # macOS DMG
|
||||
# ./scripts/build-electron.sh --help # Show help
|
||||
# ./scripts/build-electron.sh --verbose # Enable verbose logging
|
||||
#
|
||||
# NPM Script Equivalents:
|
||||
# npm run build:electron # Development build
|
||||
# npm run build:electron:package # Package build
|
||||
# npm run build:electron:appimage # AppImage package
|
||||
# npm run build:electron:deb # Debian package
|
||||
# Examples:
|
||||
# ./scripts/build-electron.sh --prod --windows # Windows production build
|
||||
# ./scripts/build-electron.sh --test --appimage # Linux AppImage test build
|
||||
# ./scripts/build-electron.sh --dev --mac # macOS development build
|
||||
#
|
||||
# Exit Codes:
|
||||
# 1 - Electron cleanup failed
|
||||
# 2 - Web build failed
|
||||
# 3 - Capacitor build failed
|
||||
# 4 - TypeScript compilation failed
|
||||
# 5 - Electron packaging failed
|
||||
# 6 - Capacitor sync failed
|
||||
# 1 - Invalid arguments
|
||||
# 2 - Electron cleanup failed
|
||||
# 3 - Web build failed
|
||||
# 4 - Capacitor sync failed
|
||||
# 5 - TypeScript compilation failed
|
||||
# 6 - Electron packaging failed
|
||||
# 7 - Asset generation failed
|
||||
# 8 - Electron app launch failed
|
||||
|
||||
@@ -36,112 +40,379 @@ set -e
|
||||
# Source common utilities
|
||||
source "$(dirname "$0")/common.sh"
|
||||
|
||||
# Parse command line arguments
|
||||
parse_args "$@"
|
||||
|
||||
# Print build header
|
||||
print_header "TimeSafari Electron Build Process"
|
||||
log_info "Starting Electron build process at $(date)"
|
||||
|
||||
# Setup environment for Electron build
|
||||
setup_build_env "electron"
|
||||
|
||||
# Setup application directories
|
||||
setup_app_directories
|
||||
|
||||
# Load environment from .env file if it exists
|
||||
load_env_file ".env"
|
||||
|
||||
# Step 1: Clean Electron app
|
||||
safe_execute "Cleaning Electron app" "npm run clean:electron || true" || exit 1
|
||||
|
||||
# Step 2: Clean dist directory
|
||||
log_info "Cleaning dist directory..."
|
||||
clean_build_artifacts "dist" "electron/app"
|
||||
|
||||
# Step 3: Build Capacitor version for Electron
|
||||
safe_execute "Building Electron version" "npm run build:electron" || exit 2
|
||||
|
||||
# Step 4: Prepare Electron app directory
|
||||
log_info "Preparing Electron app directory..."
|
||||
mkdir -p electron/app
|
||||
|
||||
# Step 5: Copy built files to Electron
|
||||
safe_execute "Copying web assets to Electron" "cp -r dist/* electron/app/" || exit 3
|
||||
|
||||
# Step 6: Validate and copy Capacitor configuration
|
||||
safe_execute "Validating Capacitor configuration" "cp capacitor.config.json electron/capacitor.config.json" || exit 3
|
||||
|
||||
# Step 7: Navigate to electron directory and build TypeScript
|
||||
safe_execute "Compiling TypeScript" "cd electron && npm run build && cd .." || exit 4
|
||||
|
||||
# Step 8: Sync with Capacitor (if needed)
|
||||
safe_execute "Syncing with Capacitor" "npx cap sync electron || true" || exit 6
|
||||
|
||||
# Step 9: Generate assets (if available)
|
||||
safe_execute "Generating assets" "npx capacitor-assets generate --electron || true" || exit 7
|
||||
|
||||
# Determine build action based on arguments
|
||||
# Default values
|
||||
BUILD_MODE="development"
|
||||
BUILD_PLATFORM=""
|
||||
BUILD_PACKAGE=""
|
||||
BUILD_ACTION="dev"
|
||||
PACKAGE_TYPE=""
|
||||
VERBOSE=false
|
||||
|
||||
# Parse additional arguments for build type
|
||||
for arg in "$@"; do
|
||||
case $arg in
|
||||
--package|--build)
|
||||
BUILD_ACTION="package"
|
||||
# Parse command line arguments
|
||||
parse_electron_args() {
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case $1 in
|
||||
--dev|--development)
|
||||
BUILD_MODE="development"
|
||||
BUILD_ACTION="dev"
|
||||
shift
|
||||
;;
|
||||
--test)
|
||||
BUILD_MODE="test"
|
||||
BUILD_ACTION="package"
|
||||
shift
|
||||
;;
|
||||
--prod|--production)
|
||||
BUILD_MODE="production"
|
||||
BUILD_ACTION="package"
|
||||
shift
|
||||
;;
|
||||
--windows)
|
||||
BUILD_PLATFORM="windows"
|
||||
shift
|
||||
;;
|
||||
--mac)
|
||||
BUILD_PLATFORM="mac"
|
||||
shift
|
||||
;;
|
||||
--linux)
|
||||
BUILD_PLATFORM="linux"
|
||||
shift
|
||||
;;
|
||||
--appimage)
|
||||
BUILD_PACKAGE="appimage"
|
||||
BUILD_PLATFORM="linux"
|
||||
shift
|
||||
;;
|
||||
--deb)
|
||||
BUILD_PACKAGE="deb"
|
||||
BUILD_PLATFORM="linux"
|
||||
shift
|
||||
;;
|
||||
--dmg)
|
||||
BUILD_PACKAGE="dmg"
|
||||
BUILD_PLATFORM="mac"
|
||||
shift
|
||||
;;
|
||||
--help)
|
||||
show_electron_help
|
||||
exit 0
|
||||
;;
|
||||
--clean)
|
||||
BUILD_ACTION="clean"
|
||||
shift
|
||||
;;
|
||||
--verbose)
|
||||
VERBOSE=true
|
||||
shift
|
||||
;;
|
||||
*)
|
||||
log_error "Unknown argument: $1"
|
||||
show_electron_help
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
}
|
||||
|
||||
# Show help information
|
||||
show_electron_help() {
|
||||
cat << EOF
|
||||
TimeSafari Electron Build Script
|
||||
|
||||
Usage: $0 [OPTIONS]
|
||||
|
||||
Build Modes:
|
||||
--dev, --development Development build (runs app)
|
||||
--test Test environment build
|
||||
--prod, --production Production environment build
|
||||
--clean Clean Electron build artifacts only
|
||||
|
||||
Platforms:
|
||||
--windows Windows build
|
||||
--mac macOS build
|
||||
--linux Linux build
|
||||
|
||||
Packages:
|
||||
--appimage Linux AppImage
|
||||
--deb Debian package
|
||||
--dmg macOS DMG
|
||||
|
||||
Options:
|
||||
--verbose Enable verbose logging
|
||||
--help Show this help message
|
||||
|
||||
Platform Validation:
|
||||
The script validates that the target platform matches the current
|
||||
execution platform. Cross-platform builds are not supported and
|
||||
will fail with an error message.
|
||||
|
||||
Examples:
|
||||
$0 --prod --windows # Windows production build
|
||||
$0 --test --appimage # Linux AppImage test build
|
||||
$0 --dev --mac # macOS development build
|
||||
$0 --prod # Production build for all platforms
|
||||
$0 --clean # Clean Electron build artifacts only
|
||||
|
||||
EOF
|
||||
}
|
||||
|
||||
# Build web assets for Electron
|
||||
build_web_assets() {
|
||||
local mode=$1
|
||||
log_info "Building web assets for Electron (mode: $mode)"
|
||||
|
||||
if [[ "$mode" == "development" ]]; then
|
||||
safe_execute "Building web assets" "VITE_GIT_HASH=\$(git log -1 --pretty=format:%h) vite build --config vite.config.electron.mts"
|
||||
else
|
||||
safe_execute "Building web assets" "VITE_GIT_HASH=\$(git log -1 --pretty=format:%h) vite build --mode $mode --config vite.config.electron.mts"
|
||||
fi
|
||||
}
|
||||
|
||||
# Sync with Capacitor
|
||||
sync_capacitor() {
|
||||
log_info "Syncing with Capacitor"
|
||||
safe_execute "Capacitor sync" "npx cap sync electron || true"
|
||||
}
|
||||
|
||||
# Copy web assets to Electron
|
||||
copy_web_assets() {
|
||||
log_info "Copying web assets to Electron"
|
||||
safe_execute "Copying assets" "cp -r dist/* electron/app/"
|
||||
safe_execute "Copying config" "cp capacitor.config.json electron/capacitor.config.json"
|
||||
}
|
||||
|
||||
# Compile TypeScript
|
||||
compile_typescript() {
|
||||
log_info "Compiling TypeScript"
|
||||
safe_execute "TypeScript compilation" "cd electron && npm run build && cd .."
|
||||
}
|
||||
|
||||
# Generate assets
|
||||
generate_assets() {
|
||||
log_info "Generating assets"
|
||||
safe_execute "Asset generation" "npx capacitor-assets generate --electron || true"
|
||||
}
|
||||
|
||||
# Clean Electron build artifacts
|
||||
clean_electron_artifacts() {
|
||||
log_info "Cleaning Electron build artifacts"
|
||||
|
||||
# Clean Electron build directory
|
||||
if [[ -d "electron/build" ]]; then
|
||||
safe_execute "Cleaning Electron build directory" "rm -rf electron/build"
|
||||
fi
|
||||
|
||||
# Clean Electron dist directory (packaged apps)
|
||||
if [[ -d "electron/dist" ]]; then
|
||||
safe_execute "Cleaning Electron dist directory" "rm -rf electron/dist"
|
||||
fi
|
||||
|
||||
# Clean Electron app directory (web assets)
|
||||
if [[ -d "electron/app" ]]; then
|
||||
safe_execute "Cleaning Electron app directory" "rm -rf electron/app"
|
||||
fi
|
||||
|
||||
# Clean TypeScript compilation artifacts
|
||||
if [[ -d "electron/src" ]]; then
|
||||
safe_execute "Cleaning TypeScript artifacts" "find electron/src -name '*.js' -delete 2>/dev/null || true"
|
||||
safe_execute "Cleaning TypeScript artifacts" "find electron/src -name '*.js.map' -delete 2>/dev/null || true"
|
||||
fi
|
||||
|
||||
log_info "✅ Electron build artifacts cleaned"
|
||||
}
|
||||
|
||||
# Detect current platform
|
||||
detect_current_platform() {
|
||||
case "$(uname -s)" in
|
||||
Linux*)
|
||||
echo "linux"
|
||||
;;
|
||||
--appimage)
|
||||
BUILD_ACTION="package"
|
||||
PACKAGE_TYPE="appimage"
|
||||
Darwin*)
|
||||
echo "mac"
|
||||
;;
|
||||
--deb)
|
||||
BUILD_ACTION="package"
|
||||
PACKAGE_TYPE="deb"
|
||||
;;
|
||||
--dev|--development)
|
||||
BUILD_ACTION="dev"
|
||||
CYGWIN*|MINGW32*|MSYS*|MINGW*)
|
||||
echo "windows"
|
||||
;;
|
||||
*)
|
||||
# Ignore unknown arguments
|
||||
log_error "Unknown platform: $(uname -s)"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
}
|
||||
|
||||
# Execute build action
|
||||
case $BUILD_ACTION in
|
||||
"package")
|
||||
if [ -n "$PACKAGE_TYPE" ]; then
|
||||
safe_execute "Building Electron package ($PACKAGE_TYPE)" "cd electron && ./build-packages.sh $PACKAGE_TYPE && cd .." || exit 5
|
||||
else
|
||||
safe_execute "Building Electron package" "cd electron && ./build-packages.sh && cd .." || exit 5
|
||||
fi
|
||||
;;
|
||||
"dev")
|
||||
safe_execute "Starting Electron development app" "cd electron && npm run electron:start && cd .." || exit 8
|
||||
;;
|
||||
*)
|
||||
log_error "Unknown build action: $BUILD_ACTION"
|
||||
# Validate platform compatibility
|
||||
validate_platform_compatibility() {
|
||||
local target_platform=$1
|
||||
local current_platform=$2
|
||||
|
||||
if [[ -n "$target_platform" && "$target_platform" != "$current_platform" ]]; then
|
||||
log_error "❌ Platform mismatch detected!"
|
||||
log_error " Target platform: $target_platform"
|
||||
log_error " Current platform: $current_platform"
|
||||
log_error ""
|
||||
log_error "Cross-platform builds are not supported."
|
||||
log_error "Please run this build on the target platform: $target_platform"
|
||||
log_error ""
|
||||
log_error "Examples:"
|
||||
log_error " - For Windows builds: Run on Windows or WSL"
|
||||
log_error " - For macOS builds: Run on macOS"
|
||||
log_error " - For Linux builds: Run on Linux"
|
||||
log_error ""
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
}
|
||||
|
||||
# Print build summary
|
||||
case $BUILD_ACTION in
|
||||
"package")
|
||||
log_success "Electron package build completed successfully!"
|
||||
if [ -d "electron/dist" ]; then
|
||||
log_info "Package files available in: electron/dist/"
|
||||
ls -la electron/dist/ || true
|
||||
fi
|
||||
;;
|
||||
"dev")
|
||||
log_success "Electron development build completed successfully!"
|
||||
log_info "Electron app should now be running"
|
||||
;;
|
||||
esac
|
||||
# Build Electron package
|
||||
build_electron_package() {
|
||||
local platform=$1
|
||||
local package=$2
|
||||
|
||||
log_info "Building Electron package (platform: $platform, package: $package)"
|
||||
|
||||
cd electron
|
||||
|
||||
if [[ -n "$package" ]]; then
|
||||
case "$package" in
|
||||
"appimage")
|
||||
safe_execute "Building AppImage" "npm run build:appimage"
|
||||
;;
|
||||
"deb")
|
||||
safe_execute "Building DEB package" "npm run build:deb"
|
||||
;;
|
||||
"dmg")
|
||||
safe_execute "Building DMG package" "npm run build:dmg"
|
||||
;;
|
||||
*)
|
||||
log_error "Unknown package type: $package"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
else
|
||||
case "$platform" in
|
||||
"windows")
|
||||
safe_execute "Building Windows package" "npm run build:windows"
|
||||
;;
|
||||
"mac")
|
||||
safe_execute "Building macOS package" "npm run build:mac"
|
||||
;;
|
||||
"linux")
|
||||
safe_execute "Building Linux package" "npm run build:linux"
|
||||
;;
|
||||
*)
|
||||
log_error "Unknown platform: $platform"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
cd ..
|
||||
}
|
||||
|
||||
print_footer "Electron Build"
|
||||
# Start Electron development
|
||||
start_electron_dev() {
|
||||
log_info "Starting Electron development"
|
||||
safe_execute "Starting Electron" "cd electron && npm run electron:start && cd .."
|
||||
}
|
||||
|
||||
# Main build function
|
||||
main_electron_build() {
|
||||
# Parse arguments
|
||||
parse_electron_args "$@"
|
||||
|
||||
# Print build header
|
||||
print_header "TimeSafari Electron Build Process"
|
||||
local current_platform=$(detect_current_platform)
|
||||
log_info "Build mode: $BUILD_MODE"
|
||||
log_info "Build platform: ${BUILD_PLATFORM:-all}"
|
||||
log_info "Build package: ${BUILD_PACKAGE:-none}"
|
||||
log_info "Build action: $BUILD_ACTION"
|
||||
log_info "Current platform: $current_platform"
|
||||
|
||||
# Early platform validation (before any build work)
|
||||
if [[ "$BUILD_ACTION" == "package" && -n "$BUILD_PLATFORM" ]]; then
|
||||
log_info "Validating platform compatibility..."
|
||||
validate_platform_compatibility "$BUILD_PLATFORM" "$current_platform"
|
||||
log_info "✅ Platform validation passed"
|
||||
fi
|
||||
|
||||
# Setup environment
|
||||
setup_build_env "electron"
|
||||
setup_app_directories
|
||||
load_env_file ".env"
|
||||
|
||||
# Step 1: Clean Electron build artifacts
|
||||
clean_electron_artifacts
|
||||
|
||||
# Step 2: Clean dist directory
|
||||
log_info "Cleaning dist directory..."
|
||||
clean_build_artifacts "dist" "electron/app"
|
||||
|
||||
# Step 3: Build web assets
|
||||
build_web_assets "$BUILD_MODE"
|
||||
|
||||
# Step 4: Prepare Electron app directory
|
||||
log_info "Preparing Electron app directory..."
|
||||
mkdir -p electron/app
|
||||
|
||||
# Step 5: Copy web assets
|
||||
copy_web_assets
|
||||
|
||||
# Step 6: Compile TypeScript
|
||||
compile_typescript
|
||||
|
||||
# Step 7: Sync with Capacitor
|
||||
sync_capacitor
|
||||
|
||||
# Step 8: Generate assets
|
||||
generate_assets
|
||||
|
||||
# Step 9: Execute build action
|
||||
case $BUILD_ACTION in
|
||||
"clean")
|
||||
clean_electron_artifacts
|
||||
log_success "Electron build artifacts cleaned successfully!"
|
||||
print_footer "Electron Clean"
|
||||
exit 0
|
||||
;;
|
||||
"dev")
|
||||
start_electron_dev
|
||||
;;
|
||||
"package")
|
||||
if [[ -n "$BUILD_PLATFORM" ]]; then
|
||||
build_electron_package "$BUILD_PLATFORM" "$BUILD_PACKAGE"
|
||||
else
|
||||
log_info "No specific platform requested, building for all platforms"
|
||||
build_electron_package "windows" "$BUILD_PACKAGE"
|
||||
build_electron_package "mac" "$BUILD_PACKAGE"
|
||||
build_electron_package "linux" "$BUILD_PACKAGE"
|
||||
fi
|
||||
;;
|
||||
*)
|
||||
log_error "Unknown build action: $BUILD_ACTION"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
# Print build summary
|
||||
case $BUILD_ACTION in
|
||||
"package")
|
||||
log_success "Electron package build completed successfully!"
|
||||
if [[ -d "electron/dist" ]]; then
|
||||
log_info "Package files available in: electron/dist/"
|
||||
ls -la electron/dist/ || true
|
||||
fi
|
||||
;;
|
||||
"dev")
|
||||
log_success "Electron development build completed successfully!"
|
||||
log_info "Electron app should now be running"
|
||||
;;
|
||||
esac
|
||||
|
||||
print_footer "Electron Build"
|
||||
}
|
||||
|
||||
# Run main function with all arguments
|
||||
main_electron_build "$@"
|
||||
|
||||
# Exit with success
|
||||
exit 0
|
||||
Reference in New Issue
Block a user