jsnbuchanan/crowd-funder-for-time-pwa
1
0
Fork 1
forked from trent_larson/crowd-funder-for-time-pwa
Code Issues Pull Requests Projects Releases Wiki Activity

refactor: implement clean modular Electron build system

Browse Source 
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
2025-07-11 06:33:21 +00:00
parent fe739f013e
commit 5f790dd90b
6 changed files with 1977 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files

533
BUILDING.md
View File

@@ -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