trent_larson
/
crowd-funder-for-time-pwa
4
1
Fork 2
Code Pull Requests 11 Releases 5 Wiki Activity
Browse Source

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.
pull/142/head
Matthew Raymer 2 weeks ago
parent
fe739f013e
commit
5f790dd90b
6 changed files with 1969 additions and 184 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 539
      BUILDING.md
  2. 594
      docs/electron-build-patterns.md
  3. 499
      electron/README.md
  4. 8
      electron/package.json
  5. 42
      package.json
  6. 471
      scripts/build-electron.sh

539
BUILDING.md
View File

@ -204,54 +204,373 @@ docker run -d \
## Desktop Build (Electron) ## 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 #### Development Build
npm run build:electron-prod
```
2. Package the Electron app for Linux: ```bash
# Start development build (runs app)
npm run build:electron:dev
```bash # Development build only
# For AppImage (recommended) npm run build:electron --dev
npm run electron:build-linux ```
# For .deb package #### Production Build
npm run electron:build-linux-deb
```
3. The packaged applications will be in `dist-electron-packages/`: ```bash
- AppImage: `dist-electron-packages/TimeSafari-x.x.x.AppImage` # Production build for all platforms
- DEB: `dist-electron-packages/timesafari_x.x.x_amd64.deb` 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 ```bash
npm run build:web # AppImage for Linux
npm run build:electron npm run build:electron:appimage:prod
npm run electron:build-mac
```
2. Package the Electron app for macOS: # DEB package for Debian/Ubuntu
npm run build:electron:deb:prod
```bash # DMG for macOS
# For Intel Macs npm run build:electron:dmg:prod
npm run electron:build-mac ```
# For Universal build (Intel + Apple Silicon) #### Direct Script Usage
npm run electron:build-mac-universal
``` ```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
```
### 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
3. The packaged applications will be in `dist-electron-packages/`: # Windows production build
- `.app` bundle: `TimeSafari.app` npm run build:electron:windows:prod
- `.dmg` installer: `TimeSafari-x.x.x.dmg` ```
- `.zip` archive: `TimeSafari-x.x.x-mac.zip`
**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
### Code Signing and Notarization (macOS) **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: 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: 2. Build with signing:
```bash ```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 ### Running the Packaged App
- **Linux**: #### 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
```
- **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
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
### Development Testing
For testing the Electron build before packaging:
- **AppImage**: Make executable and run
```bash
chmod +x electron/dist/TimeSafari-*.AppImage
./electron/dist/TimeSafari-*.AppImage
```
- **DEB**: Install and run
```bash
sudo dpkg -i electron/dist/timesafari_*_amd64.deb
timesafari
```
#### 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
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 ```bash
# Build and run in development mode (includes DevTools) # Clean and rebuild
npm run electron:dev npm run clean:electron
cd electron && npm run build
```
# Build in production mode and test **Native Module Issues**:
npm run build:electron-prod && npm run electron:start ```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) ## Mobile Builds (Capacitor)
### iOS Build ### iOS Build

594
docs/electron-build-patterns.md
View 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
View 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

8
electron/package.json
View File

@ -18,7 +18,13 @@
"electron:start-live": "node ./live-runner.js", "electron:start-live": "node ./live-runner.js",
"electron:start": "npm run build && electron --inspect=5858 ./", "electron:start": "npm run build && electron --inspect=5858 ./",
"electron:pack": "npm run build && electron-builder build --dir -c ./electron-builder.config.json", "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": { "dependencies": {
"@capacitor-community/electron": "^5.0.0", "@capacitor-community/electron": "^5.0.0",

42
package.json
View File

@ -9,7 +9,6 @@
"lint": "eslint --ext .js,.ts,.vue --ignore-path .gitignore src", "lint": "eslint --ext .js,.ts,.vue --ignore-path .gitignore src",
"lint-fix": "eslint --ext .js,.ts,.vue --ignore-path .gitignore --fix 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", "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:prerequisites": "node scripts/check-prerequisites.js",
"test:web": "npx playwright test -c playwright.config-local.ts --trace on", "test:web": "npx playwright test -c playwright.config-local.ts --trace on",
"test:mobile": "./scripts/test-mobile.sh", "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:up:prod": "npm run build:web:build -- --mode production && docker-compose up production",
"docker:down": "docker-compose down", "docker:down": "docker-compose down",
"docker:logs": "docker-compose logs -f", "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", "build:electron": "./scripts/build-electron.sh",
"electron:dev": "npm run build:electron && npx cap copy electron && cd electron && npm run electron:start", "build:electron:dev": "./scripts/build-electron.sh --dev",
"electron:setup": "./scripts/setup-electron.sh", "build:electron:test": "./scripts/build-electron.sh --test",
"electron:dev-full": "./scripts/electron-dev.sh", "build:electron:prod": "./scripts/build-electron.sh --prod",
"electron:build": "npm run build:electron && npx cap copy electron && cd electron && ./build-packages.sh", "build:electron:windows": "./scripts/build-electron.sh --prod --windows",
"electron:build:appimage": "npm run build:electron && npx cap copy electron && cd electron && ./build-packages.sh appimage", "build:electron:windows:dev": "./scripts/build-electron.sh --dev --windows",
"electron:build:deb": "npm run build:electron && npx cap copy electron && cd electron && ./build-packages.sh deb", "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: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: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: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:beta": "cd ios && fastlane beta",
"fastlane:ios:release": "cd ios && fastlane release", "fastlane:ios:release": "cd ios && fastlane release",
"fastlane:android:beta": "cd android && fastlane beta", "fastlane:android:beta": "cd android && fastlane beta",

471
scripts/build-electron.sh
View File

@ -1,32 +1,36 @@
#!/bin/bash #!/bin/bash
# build-electron.sh # build-electron.sh
# Author: Matthew Raymer # Author: Matthew Raymer
# Description: Electron build script for TimeSafari application # Description: Clean, modular Electron build script for TimeSafari application
# This script handles the complete Electron build process including cleanup, # This script handles Electron builds with proper separation of concerns and
# web build, Capacitor build, TypeScript compilation, and Electron packaging. # no command chaining, following DRY principles.
# #
# Usage: # Usage:
# ./scripts/build-electron.sh # Development build (runs app) # ./scripts/build-electron.sh # Development build (runs app)
# ./scripts/build-electron.sh --dev # 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 --test # Test environment build
# ./scripts/build-electron.sh --appimage # Build AppImage package # ./scripts/build-electron.sh --prod # Production environment build
# ./scripts/build-electron.sh --deb # Build Debian package # ./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 --help # Show help
# ./scripts/build-electron.sh --verbose # Enable verbose logging # ./scripts/build-electron.sh --verbose # Enable verbose logging
# #
# NPM Script Equivalents: # Examples:
# npm run build:electron # Development build # ./scripts/build-electron.sh --prod --windows # Windows production build
# npm run build:electron:package # Package build # ./scripts/build-electron.sh --test --appimage # Linux AppImage test build
# npm run build:electron:appimage # AppImage package # ./scripts/build-electron.sh --dev --mac # macOS development build
# npm run build:electron:deb # Debian package
# #
# Exit Codes: # Exit Codes:
# 1 - Electron cleanup failed # 1 - Invalid arguments
# 2 - Web build failed # 2 - Electron cleanup failed
# 3 - Capacitor build failed # 3 - Web build failed
# 4 - TypeScript compilation failed # 4 - Capacitor sync failed
# 5 - Electron packaging failed # 5 - TypeScript compilation failed
# 6 - Capacitor sync failed # 6 - Electron packaging failed
# 7 - Asset generation failed # 7 - Asset generation failed
# 8 - Electron app launch failed # 8 - Electron app launch failed
@ -36,112 +40,379 @@ set -e
# Source common utilities # Source common utilities
source "$(dirname "$0")/common.sh" source "$(dirname "$0")/common.sh"
# Default values
BUILD_MODE="development"
BUILD_PLATFORM=""
BUILD_PACKAGE=""
BUILD_ACTION="dev"
VERBOSE=false
# Parse command line arguments # Parse command line arguments
parse_args "$@" 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
}
# Print build header # Show help information
print_header "TimeSafari Electron Build Process" show_electron_help() {
log_info "Starting Electron build process at $(date)" cat << EOF
TimeSafari Electron Build Script
# Setup environment for Electron build Usage: $0 [OPTIONS]
setup_build_env "electron"
# Setup application directories Build Modes:
setup_app_directories --dev, --development Development build (runs app)
--test Test environment build
--prod, --production Production environment build
--clean Clean Electron build artifacts only
# Load environment from .env file if it exists Platforms:
load_env_file ".env" --windows Windows build
--mac macOS build
--linux Linux build
# Step 1: Clean Electron app Packages:
safe_execute "Cleaning Electron app" "npm run clean:electron || true" || exit 1 --appimage Linux AppImage
--deb Debian package
--dmg macOS DMG
# Step 2: Clean dist directory Options:
log_info "Cleaning dist directory..." --verbose Enable verbose logging
clean_build_artifacts "dist" "electron/app" --help Show this help message
# Step 3: Build Capacitor version for Electron Platform Validation:
safe_execute "Building Electron version" "npm run build:electron" || exit 2 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.
# Step 4: Prepare Electron app directory Examples:
log_info "Preparing Electron app directory..." $0 --prod --windows # Windows production build
mkdir -p electron/app $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
# Step 5: Copy built files to Electron EOF
safe_execute "Copying web assets to Electron" "cp -r dist/* electron/app/" || exit 3 }
# Step 6: Validate and copy Capacitor configuration # Build web assets for Electron
safe_execute "Validating Capacitor configuration" "cp capacitor.config.json electron/capacitor.config.json" || exit 3 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
}
# Step 7: Navigate to electron directory and build TypeScript # Sync with Capacitor
safe_execute "Compiling TypeScript" "cd electron && npm run build && cd .." || exit 4 sync_capacitor() {
log_info "Syncing with Capacitor"
safe_execute "Capacitor sync" "npx cap sync electron || true"
}
# Step 8: Sync with Capacitor (if needed) # Copy web assets to Electron
safe_execute "Syncing with Capacitor" "npx cap sync electron || true" || exit 6 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"
}
# Step 9: Generate assets (if available) # Compile TypeScript
safe_execute "Generating assets" "npx capacitor-assets generate --electron || true" || exit 7 compile_typescript() {
log_info "Compiling TypeScript"
safe_execute "TypeScript compilation" "cd electron && npm run build && cd .."
}
# Determine build action based on arguments # Generate assets
BUILD_ACTION="dev" generate_assets() {
PACKAGE_TYPE="" log_info "Generating assets"
safe_execute "Asset generation" "npx capacitor-assets generate --electron || true"
}
# Parse additional arguments for build type # Clean Electron build artifacts
for arg in "$@"; do clean_electron_artifacts() {
case $arg in log_info "Cleaning Electron build artifacts"
--package|--build)
BUILD_ACTION="package" # Clean Electron build directory
;; if [[ -d "electron/build" ]]; then
--appimage) safe_execute "Cleaning Electron build directory" "rm -rf electron/build"
BUILD_ACTION="package" fi
PACKAGE_TYPE="appimage"
# 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"
;; ;;
--deb) Darwin*)
BUILD_ACTION="package" echo "mac"
PACKAGE_TYPE="deb"
;; ;;
--dev|--development) CYGWIN*|MINGW32*|MSYS*|MINGW*)
BUILD_ACTION="dev" echo "windows"
;; ;;
*) *)
# Ignore unknown arguments log_error "Unknown platform: $(uname -s)"
exit 1
;; ;;
esac esac
done }
# Execute build action # Validate platform compatibility
case $BUILD_ACTION in validate_platform_compatibility() {
"package") local target_platform=$1
if [ -n "$PACKAGE_TYPE" ]; then local current_platform=$2
safe_execute "Building Electron package ($PACKAGE_TYPE)" "cd electron && ./build-packages.sh $PACKAGE_TYPE && cd .." || exit 5
else if [[ -n "$target_platform" && "$target_platform" != "$current_platform" ]]; then
safe_execute "Building Electron package" "cd electron && ./build-packages.sh && cd .." || exit 5 log_error "❌ Platform mismatch detected!"
fi log_error " Target platform: $target_platform"
;; log_error " Current platform: $current_platform"
"dev") log_error ""
safe_execute "Starting Electron development app" "cd electron && npm run electron:start && cd .." || exit 8 log_error "Cross-platform builds are not supported."
;; log_error "Please run this build on the target platform: $target_platform"
*) log_error ""
log_error "Unknown build action: $BUILD_ACTION" 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 exit 1
;; fi
esac }
# Print build summary # Build Electron package
case $BUILD_ACTION in build_electron_package() {
"package") local platform=$1
log_success "Electron package build completed successfully!" local package=$2
if [ -d "electron/dist" ]; then
log_info "Package files available in: electron/dist/" log_info "Building Electron package (platform: $platform, package: $package)"
ls -la electron/dist/ || true
fi cd electron
;;
"dev") if [[ -n "$package" ]]; then
log_success "Electron development build completed successfully!" case "$package" in
log_info "Electron app should now be running" "appimage")
;; safe_execute "Building AppImage" "npm run build:appimage"
esac ;;
"deb")
print_footer "Electron Build" 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 ..
}
# 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 with success
exit 0 exit 0
Write Preview
Loading…
Cancel
Save