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
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
|
||||
Reference in New Issue
Block a user