crowd-funder-for-time-pwa/electron

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

# Start development build (runs app)
npm run build:electron:dev

# Development build only
npm run build:electron -- --mode development

Production Build

# 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

# 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

# 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

# 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

# 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

# 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:

{
  "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:

{
  "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:

VITE_API_URL=http://localhost:3000
VITE_DEBUG=true
VITE_LOG_LEVEL=debug
VITE_ENABLE_DEV_TOOLS=true

Testing:

VITE_API_URL=https://test-api.timesafari.com
VITE_DEBUG=false
VITE_LOG_LEVEL=info
VITE_ENABLE_DEV_TOOLS=false

Production:

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:

# Clean and rebuild
npm run clean:electron
cd electron && npm run build

Native Module Issues:

# Rebuild native modules
cd electron && npm run build

Asset Copy Issues:

# Verify Capacitor sync
npx cap sync electron

Package Creation Failures:

# 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

- name: Build Electron
  run: |
    npm run build:electron:windows:prod
    npm run build:electron:mac:prod
    npm run build:electron:linux:prod    

Automated Testing

- 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