crowd-funder-for-time-pwa/electron/README.md

# 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