forked from jsnbuchanan/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
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
|
||||
Reference in New Issue
Block a user