From 5f790dd90b11d80bc18bcb9c473ce23a0c16a6fc Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Fri, 11 Jul 2025 06:33:21 +0000 Subject: [PATCH] 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. --- BUILDING.md | 539 +++++++++++++++++++++++++---- docs/electron-build-patterns.md | 594 ++++++++++++++++++++++++++++++++ electron/README.md | 499 +++++++++++++++++++++++++++ electron/package.json | 8 +- package.json | 42 ++- scripts/build-electron.sh | 471 +++++++++++++++++++------ 6 files changed, 1969 insertions(+), 184 deletions(-) create mode 100644 docs/electron-build-patterns.md create mode 100644 electron/README.md diff --git a/BUILDING.md b/BUILDING.md index daaa767e..f6070560 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -204,54 +204,373 @@ docker run -d \ ## Desktop Build (Electron) -### Linux Build +TimeSafari's Electron build system provides comprehensive desktop application +packaging and distribution capabilities across Windows, macOS, and Linux +platforms. The system supports multiple build modes, environment +configurations, and package formats. -1. Build the electron app in production mode: +### Quick Start - ```bash - npm run build:electron-prod - ``` +#### Development Build -2. Package the Electron app for Linux: +```bash +# Start development build (runs app) +npm run build:electron:dev - ```bash - # For AppImage (recommended) - npm run electron:build-linux +# Development build only +npm run build:electron --dev +``` - # For .deb package - npm run electron:build-linux-deb - ``` +#### Production Build -3. The packaged applications will be in `dist-electron-packages/`: - - AppImage: `dist-electron-packages/TimeSafari-x.x.x.AppImage` - - DEB: `dist-electron-packages/timesafari_x.x.x_amd64.deb` +```bash +# Production build for all platforms +npm run build:electron:prod -### macOS Build +# Platform-specific production builds +npm run build:electron:windows:prod +npm run build:electron:mac:prod +npm run build:electron:linux:prod +``` -1. Build the electron app in production mode: +#### Package-Specific Builds - ```bash - npm run build:web - npm run build:electron - npm run electron:build-mac - ``` +```bash +# AppImage for Linux +npm run build:electron:appimage:prod -2. Package the Electron app for macOS: +# DEB package for Debian/Ubuntu +npm run build:electron:deb:prod - ```bash - # For Intel Macs - npm run electron:build-mac +# DMG for macOS +npm run build:electron:dmg:prod +``` - # For Universal build (Intel + Apple Silicon) - npm run electron:build-mac-universal - ``` +#### Direct Script Usage + +```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/`: - - `.app` bundle: `TimeSafari.app` - - `.dmg` installer: `TimeSafari-x.x.x.dmg` - - `.zip` archive: `TimeSafari-x.x.x-mac.zip` +# 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 -### 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: @@ -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 - ``` - -- **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: +#### Linux +- **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 -# Build and run in development mode (includes DevTools) -npm run electron:dev +# Clean and rebuild +npm run clean:electron +cd electron && npm run build +``` -# Build in production mode and test -npm run build:electron-prod && npm run electron:start +**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 diff --git a/docs/electron-build-patterns.md b/docs/electron-build-patterns.md new file mode 100644 index 00000000..64045e0b --- /dev/null +++ b/docs/electron-build-patterns.md @@ -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 \ No newline at end of file diff --git a/electron/README.md b/electron/README.md new file mode 100644 index 00000000..6182fa83 --- /dev/null +++ b/electron/README.md @@ -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 \ No newline at end of file diff --git a/electron/package.json b/electron/package.json index daa15ca5..adcdb2ee 100644 --- a/electron/package.json +++ b/electron/package.json @@ -18,7 +18,13 @@ "electron:start-live": "node ./live-runner.js", "electron:start": "npm run build && electron --inspect=5858 ./", "electron:pack": "npm run build && electron-builder build --dir -c ./electron-builder.config.json", - "electron:make": "npm run build && electron-builder build -c ./electron-builder.config.json -p always" + "electron:make": "npm run build && electron-builder build -c ./electron-builder.config.json -p always", + "build:windows": "npm run build && electron-builder build --win -c ./electron-builder.config.json", + "build:mac": "npm run build && electron-builder build --mac -c ./electron-builder.config.json", + "build:linux": "npm run build && electron-builder build --linux -c ./electron-builder.config.json", + "build:appimage": "npm run build && electron-builder build --linux AppImage -c ./electron-builder.config.json", + "build:deb": "npm run build && electron-builder build --linux deb -c ./electron-builder.config.json", + "build:dmg": "npm run build && electron-builder build --mac dmg -c ./electron-builder.config.json" }, "dependencies": { "@capacitor-community/electron": "^5.0.0", diff --git a/package.json b/package.json index 7bd7a735..edb71cbe 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,6 @@ "lint": "eslint --ext .js,.ts,.vue --ignore-path .gitignore src", "lint-fix": "eslint --ext .js,.ts,.vue --ignore-path .gitignore --fix src", "prebuild": "eslint --ext .js,.ts,.vue --ignore-path .gitignore src && node sw_combine.js && node scripts/copy-wasm.js", - "test:all": "./scripts/test-all.sh", "test:prerequisites": "node scripts/check-prerequisites.js", "test:web": "npx playwright test -c playwright.config-local.ts --trace on", "test:mobile": "./scripts/test-mobile.sh", @@ -31,21 +30,38 @@ "docker:up:prod": "npm run build:web:build -- --mode production && docker-compose up production", "docker:down": "docker-compose down", "docker:logs": "docker-compose logs -f", - "build:electron": "VITE_GIT_HASH=`git log -1 --pretty=format:%h` vite build --mode electron --config vite.config.electron.mts", - "electron:dev": "npm run build:electron && npx cap copy electron && cd electron && npm run electron:start", - "electron:setup": "./scripts/setup-electron.sh", - "electron:dev-full": "./scripts/electron-dev.sh", - "electron:build": "npm run build:electron && npx cap copy electron && cd electron && ./build-packages.sh", - "electron:build:appimage": "npm run build:electron && npx cap copy electron && cd electron && ./build-packages.sh appimage", - "electron:build:deb": "npm run build:electron && npx cap copy electron && cd electron && ./build-packages.sh deb", + "build:electron": "./scripts/build-electron.sh", + "build:electron:dev": "./scripts/build-electron.sh --dev", + "build:electron:test": "./scripts/build-electron.sh --test", + "build:electron:prod": "./scripts/build-electron.sh --prod", + "build:electron:windows": "./scripts/build-electron.sh --prod --windows", + "build:electron:windows:dev": "./scripts/build-electron.sh --dev --windows", + "build:electron:windows:test": "./scripts/build-electron.sh --test --windows", + "build:electron:windows:prod": "./scripts/build-electron.sh --prod --windows", + "build:electron:mac": "./scripts/build-electron.sh --prod --mac", + "build:electron:mac:dev": "./scripts/build-electron.sh --dev --mac", + "build:electron:mac:test": "./scripts/build-electron.sh --test --mac", + "build:electron:mac:prod": "./scripts/build-electron.sh --prod --mac", + "build:electron:linux": "./scripts/build-electron.sh --prod --linux", + "build:electron:linux:dev": "./scripts/build-electron.sh --dev --linux", + "build:electron:linux:test": "./scripts/build-electron.sh --test --linux", + "build:electron:linux:prod": "./scripts/build-electron.sh --prod --linux", + "build:electron:appimage": "./scripts/build-electron.sh --prod --appimage", + "build:electron:appimage:dev": "./scripts/build-electron.sh --dev --appimage", + "build:electron:appimage:test": "./scripts/build-electron.sh --test --appimage", + "build:electron:appimage:prod": "./scripts/build-electron.sh --prod --appimage", + "build:electron:deb": "./scripts/build-electron.sh --prod --deb", + "build:electron:deb:dev": "./scripts/build-electron.sh --dev --deb", + "build:electron:deb:test": "./scripts/build-electron.sh --test --deb", + "build:electron:deb:prod": "./scripts/build-electron.sh --prod --deb", + "build:electron:dmg": "./scripts/build-electron.sh --prod --dmg", + "build:electron:dmg:dev": "./scripts/build-electron.sh --dev --dmg", + "build:electron:dmg:test": "./scripts/build-electron.sh --test --dmg", + "build:electron:dmg:prod": "./scripts/build-electron.sh --prod --dmg", "clean:android": "adb uninstall app.timesafari.app || true", - "clean:electron": "rm -rf electron/app/* electron/dist/* || true", "clean:ios": "rm -rf ios/App/build ios/App/Pods ios/App/output ios/App/App/public ios/DerivedData ios/capacitor-cordova-ios-plugins ios/App/App/capacitor.config.json ios/App/App/config.xml || true", + "clean:electron": "./scripts/build-electron.sh --clean", "build:android": "./scripts/build-android.sh", - "build:electron:all": "./scripts/build-electron.sh", - "build:electron:package": "./scripts/build-electron.sh --package", - "build:electron:appimage": "./scripts/build-electron.sh --appimage", - "build:electron:deb": "./scripts/build-electron.sh --deb", "fastlane:ios:beta": "cd ios && fastlane beta", "fastlane:ios:release": "cd ios && fastlane release", "fastlane:android:beta": "cd android && fastlane beta", diff --git a/scripts/build-electron.sh b/scripts/build-electron.sh index 6570a7a5..561506bd 100755 --- a/scripts/build-electron.sh +++ b/scripts/build-electron.sh @@ -1,32 +1,36 @@ #!/bin/bash # build-electron.sh # Author: Matthew Raymer -# Description: Electron build script for TimeSafari application -# This script handles the complete Electron build process including cleanup, -# web build, Capacitor build, TypeScript compilation, and Electron packaging. +# Description: Clean, modular Electron build script for TimeSafari application +# This script handles Electron builds with proper separation of concerns and +# no command chaining, following DRY principles. # # Usage: # ./scripts/build-electron.sh # Development build (runs app) # ./scripts/build-electron.sh --dev # Development build (runs app) -# ./scripts/build-electron.sh --package # Package build (creates distributable) -# ./scripts/build-electron.sh --appimage # Build AppImage package -# ./scripts/build-electron.sh --deb # Build Debian package +# ./scripts/build-electron.sh --test # Test environment build +# ./scripts/build-electron.sh --prod # Production environment build +# ./scripts/build-electron.sh --windows # Windows build +# ./scripts/build-electron.sh --mac # macOS build +# ./scripts/build-electron.sh --linux # Linux build +# ./scripts/build-electron.sh --appimage # Linux AppImage +# ./scripts/build-electron.sh --deb # Debian package +# ./scripts/build-electron.sh --dmg # macOS DMG # ./scripts/build-electron.sh --help # Show help # ./scripts/build-electron.sh --verbose # Enable verbose logging # -# NPM Script Equivalents: -# npm run build:electron # Development build -# npm run build:electron:package # Package build -# npm run build:electron:appimage # AppImage package -# npm run build:electron:deb # Debian package +# Examples: +# ./scripts/build-electron.sh --prod --windows # Windows production build +# ./scripts/build-electron.sh --test --appimage # Linux AppImage test build +# ./scripts/build-electron.sh --dev --mac # macOS development build # # Exit Codes: -# 1 - Electron cleanup failed -# 2 - Web build failed -# 3 - Capacitor build failed -# 4 - TypeScript compilation failed -# 5 - Electron packaging failed -# 6 - Capacitor sync failed +# 1 - Invalid arguments +# 2 - Electron cleanup failed +# 3 - Web build failed +# 4 - Capacitor sync failed +# 5 - TypeScript compilation failed +# 6 - Electron packaging failed # 7 - Asset generation failed # 8 - Electron app launch failed @@ -36,112 +40,379 @@ set -e # Source common utilities source "$(dirname "$0")/common.sh" +# Default values +BUILD_MODE="development" +BUILD_PLATFORM="" +BUILD_PACKAGE="" +BUILD_ACTION="dev" +VERBOSE=false + # 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 -print_header "TimeSafari Electron Build Process" -log_info "Starting Electron build process at $(date)" +# Show help information +show_electron_help() { + cat << EOF +TimeSafari Electron Build Script -# Setup environment for Electron build -setup_build_env "electron" +Usage: $0 [OPTIONS] -# Setup application directories -setup_app_directories +Build Modes: + --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 -load_env_file ".env" +Platforms: + --windows Windows build + --mac macOS build + --linux Linux build -# Step 1: Clean Electron app -safe_execute "Cleaning Electron app" "npm run clean:electron || true" || exit 1 +Packages: + --appimage Linux AppImage + --deb Debian package + --dmg macOS DMG -# Step 2: Clean dist directory -log_info "Cleaning dist directory..." -clean_build_artifacts "dist" "electron/app" +Options: + --verbose Enable verbose logging + --help Show this help message -# Step 3: Build Capacitor version for Electron -safe_execute "Building Electron version" "npm run build:electron" || exit 2 +Platform Validation: + The script validates that the target platform matches the current + execution platform. Cross-platform builds are not supported and + will fail with an error message. -# Step 4: Prepare Electron app directory -log_info "Preparing Electron app directory..." -mkdir -p electron/app +Examples: + $0 --prod --windows # Windows production build + $0 --test --appimage # Linux AppImage test build + $0 --dev --mac # macOS development build + $0 --prod # Production build for all platforms + $0 --clean # Clean Electron build artifacts only -# Step 5: Copy built files to Electron -safe_execute "Copying web assets to Electron" "cp -r dist/* electron/app/" || exit 3 +EOF +} -# Step 6: Validate and copy Capacitor configuration -safe_execute "Validating Capacitor configuration" "cp capacitor.config.json electron/capacitor.config.json" || exit 3 +# Build web assets for Electron +build_web_assets() { + local mode=$1 + log_info "Building web assets for Electron (mode: $mode)" + + if [[ "$mode" == "development" ]]; then + safe_execute "Building web assets" "VITE_GIT_HASH=\$(git log -1 --pretty=format:%h) vite build --config vite.config.electron.mts" + else + safe_execute "Building web assets" "VITE_GIT_HASH=\$(git log -1 --pretty=format:%h) vite build --mode $mode --config vite.config.electron.mts" + fi +} -# Step 7: Navigate to electron directory and build TypeScript -safe_execute "Compiling TypeScript" "cd electron && npm run build && cd .." || exit 4 +# Sync with Capacitor +sync_capacitor() { + log_info "Syncing with Capacitor" + safe_execute "Capacitor sync" "npx cap sync electron || true" +} -# Step 8: Sync with Capacitor (if needed) -safe_execute "Syncing with Capacitor" "npx cap sync electron || true" || exit 6 +# Copy web assets to Electron +copy_web_assets() { + log_info "Copying web assets to Electron" + safe_execute "Copying assets" "cp -r dist/* electron/app/" + safe_execute "Copying config" "cp capacitor.config.json electron/capacitor.config.json" +} -# Step 9: Generate assets (if available) -safe_execute "Generating assets" "npx capacitor-assets generate --electron || true" || exit 7 +# Compile TypeScript +compile_typescript() { + log_info "Compiling TypeScript" + safe_execute "TypeScript compilation" "cd electron && npm run build && cd .." +} -# Determine build action based on arguments -BUILD_ACTION="dev" -PACKAGE_TYPE="" +# Generate assets +generate_assets() { + log_info "Generating assets" + safe_execute "Asset generation" "npx capacitor-assets generate --electron || true" +} -# Parse additional arguments for build type -for arg in "$@"; do - case $arg in - --package|--build) - BUILD_ACTION="package" - ;; - --appimage) - BUILD_ACTION="package" - PACKAGE_TYPE="appimage" +# Clean Electron build artifacts +clean_electron_artifacts() { + log_info "Cleaning Electron build artifacts" + + # Clean Electron build directory + if [[ -d "electron/build" ]]; then + safe_execute "Cleaning Electron build directory" "rm -rf electron/build" + fi + + # Clean Electron dist directory (packaged apps) + if [[ -d "electron/dist" ]]; then + safe_execute "Cleaning Electron dist directory" "rm -rf electron/dist" + fi + + # Clean Electron app directory (web assets) + if [[ -d "electron/app" ]]; then + safe_execute "Cleaning Electron app directory" "rm -rf electron/app" + fi + + # Clean TypeScript compilation artifacts + if [[ -d "electron/src" ]]; then + safe_execute "Cleaning TypeScript artifacts" "find electron/src -name '*.js' -delete 2>/dev/null || true" + safe_execute "Cleaning TypeScript artifacts" "find electron/src -name '*.js.map' -delete 2>/dev/null || true" + fi + + log_info "✅ Electron build artifacts cleaned" +} + +# Detect current platform +detect_current_platform() { + case "$(uname -s)" in + Linux*) + echo "linux" ;; - --deb) - BUILD_ACTION="package" - PACKAGE_TYPE="deb" + Darwin*) + echo "mac" ;; - --dev|--development) - BUILD_ACTION="dev" + CYGWIN*|MINGW32*|MSYS*|MINGW*) + echo "windows" ;; *) - # Ignore unknown arguments + log_error "Unknown platform: $(uname -s)" + exit 1 ;; esac -done - -# Execute build action -case $BUILD_ACTION in - "package") - if [ -n "$PACKAGE_TYPE" ]; then - safe_execute "Building Electron package ($PACKAGE_TYPE)" "cd electron && ./build-packages.sh $PACKAGE_TYPE && cd .." || exit 5 - else - safe_execute "Building Electron package" "cd electron && ./build-packages.sh && cd .." || exit 5 - fi - ;; - "dev") - safe_execute "Starting Electron development app" "cd electron && npm run electron:start && cd .." || exit 8 - ;; - *) - log_error "Unknown build action: $BUILD_ACTION" +} + +# Validate platform compatibility +validate_platform_compatibility() { + local target_platform=$1 + local current_platform=$2 + + if [[ -n "$target_platform" && "$target_platform" != "$current_platform" ]]; then + log_error "❌ Platform mismatch detected!" + log_error " Target platform: $target_platform" + log_error " Current platform: $current_platform" + log_error "" + log_error "Cross-platform builds are not supported." + log_error "Please run this build on the target platform: $target_platform" + log_error "" + log_error "Examples:" + log_error " - For Windows builds: Run on Windows or WSL" + log_error " - For macOS builds: Run on macOS" + log_error " - For Linux builds: Run on Linux" + log_error "" exit 1 - ;; -esac - -# 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" + fi +} + +# Build Electron package +build_electron_package() { + local platform=$1 + local package=$2 + + log_info "Building Electron package (platform: $platform, package: $package)" + + cd electron + + if [[ -n "$package" ]]; then + case "$package" in + "appimage") + safe_execute "Building AppImage" "npm run build:appimage" + ;; + "deb") + safe_execute "Building DEB package" "npm run build:deb" + ;; + "dmg") + safe_execute "Building DMG package" "npm run build:dmg" + ;; + *) + log_error "Unknown package type: $package" + exit 1 + ;; + esac + else + case "$platform" in + "windows") + safe_execute "Building Windows package" "npm run build:windows" + ;; + "mac") + safe_execute "Building macOS package" "npm run build:mac" + ;; + "linux") + safe_execute "Building Linux package" "npm run build:linux" + ;; + *) + log_error "Unknown platform: $platform" + exit 1 + ;; + esac + fi + + cd .. +} + +# Start Electron development +start_electron_dev() { + log_info "Starting Electron development" + safe_execute "Starting Electron" "cd electron && npm run electron:start && cd .." +} + +# Main build function +main_electron_build() { + # Parse arguments + parse_electron_args "$@" + + # Print build header + print_header "TimeSafari Electron Build Process" + local current_platform=$(detect_current_platform) + log_info "Build mode: $BUILD_MODE" + log_info "Build platform: ${BUILD_PLATFORM:-all}" + log_info "Build package: ${BUILD_PACKAGE:-none}" + log_info "Build action: $BUILD_ACTION" + log_info "Current platform: $current_platform" + + # Early platform validation (before any build work) + if [[ "$BUILD_ACTION" == "package" && -n "$BUILD_PLATFORM" ]]; then + log_info "Validating platform compatibility..." + validate_platform_compatibility "$BUILD_PLATFORM" "$current_platform" + log_info "✅ Platform validation passed" + fi + + # Setup environment + setup_build_env "electron" + setup_app_directories + load_env_file ".env" + + # Step 1: Clean Electron build artifacts + clean_electron_artifacts + + # Step 2: Clean dist directory + log_info "Cleaning dist directory..." + clean_build_artifacts "dist" "electron/app" + + # Step 3: Build web assets + build_web_assets "$BUILD_MODE" + + # Step 4: Prepare Electron app directory + log_info "Preparing Electron app directory..." + mkdir -p electron/app + + # Step 5: Copy web assets + copy_web_assets + + # Step 6: Compile TypeScript + compile_typescript + + # Step 7: Sync with Capacitor + sync_capacitor + + # Step 8: Generate assets + generate_assets + + # Step 9: Execute build action + case $BUILD_ACTION in + "clean") + clean_electron_artifacts + log_success "Electron build artifacts cleaned successfully!" + print_footer "Electron Clean" + exit 0 + ;; + "dev") + start_electron_dev + ;; + "package") + if [[ -n "$BUILD_PLATFORM" ]]; then + build_electron_package "$BUILD_PLATFORM" "$BUILD_PACKAGE" + else + log_info "No specific platform requested, building for all platforms" + build_electron_package "windows" "$BUILD_PACKAGE" + build_electron_package "mac" "$BUILD_PACKAGE" + build_electron_package "linux" "$BUILD_PACKAGE" + fi + ;; + *) + log_error "Unknown build action: $BUILD_ACTION" + exit 1 + ;; + esac + + # Print build summary + case $BUILD_ACTION in + "package") + log_success "Electron package build completed successfully!" + if [[ -d "electron/dist" ]]; then + log_info "Package files available in: electron/dist/" + ls -la electron/dist/ || true + fi + ;; + "dev") + log_success "Electron development build completed successfully!" + log_info "Electron app should now be running" + ;; + esac + + print_footer "Electron Build" +} + +# Run main function with all arguments +main_electron_build "$@" # Exit with success exit 0 \ No newline at end of file