# TimeSafari Electron Build Guide **Author**: Matthew Raymer **Date**: 2025-01-10 **Status**: **ACTIVE** - Production Ready ## Overview This guide covers building and running the TimeSafari Electron application for desktop platforms (Windows, macOS, Linux). ## Prerequisites - Node.js 18+ and npm - TypeScript - Electron Builder - Platform-specific build tools (see below) ## Quick Start ### Development Mode ```bash # Start development server npm run build:electron:dev # Or manually cd electron npm run electron:start ``` ### Production Builds ```bash # Build for current platform npm run build:electron:prod # Platform-specific builds npm run build:electron:windows npm run build:electron:mac npm run build:electron:linux # Package-specific builds npm run build:electron:appimage # Linux AppImage npm run build:electron:dmg # macOS DMG installer npm run build:electron:deb # Linux DEB package ``` ## Single Instance Enforcement The Electron app enforces single instance operation to prevent database conflicts and resource contention: ### Implementation - Uses Electron's built-in `app.requestSingleInstanceLock()` - Second instances exit immediately with user-friendly message - Existing instance focuses and shows informational dialog ### Behavior - **First instance**: Starts normally and acquires lock - **Second instance**: Detects existing instance, exits immediately - **User experience**: Clear messaging about single instance requirement ### Benefits - Prevents database corruption from concurrent access - Avoids resource conflicts - Maintains data integrity - User-friendly error handling ## Build Configuration ### Environment Modes ```bash # Development (default) npm run build:electron:dev # Testing npm run build:electron:test # Production npm run build:electron:prod ``` ### Platform-Specific Builds ```bash # Windows npm run build:electron:windows:dev npm run build:electron:windows:test npm run build:electron:windows:prod # macOS npm run build:electron:mac:dev npm run build:electron:mac:test npm run build:electron:mac:prod # Linux npm run build:electron:linux:dev npm run build:electron:linux:test npm run build:electron:linux:prod ``` ### Package Types ```bash # Linux AppImage npm run build:electron:appimage:dev npm run build:electron:appimage:test npm run build:electron:appimage:prod # macOS DMG npm run build:electron:dmg:dev npm run build:electron:dmg:test npm run build:electron:dmg:prod # Linux DEB npm run build:electron:deb:dev npm run build:electron:deb:test npm run build:electron:deb:prod ``` ## Platform-Specific Requirements ### Windows - Windows 10+ (64-bit) - Visual Studio Build Tools (for native modules) ### macOS - macOS 10.15+ (Catalina) - Xcode Command Line Tools - Code signing certificate (for distribution) ### Linux - Ubuntu 18.04+ / Debian 10+ / CentOS 7+ - Development headers for native modules ## Database Configuration ### SQLite Integration - Uses native Node.js SQLite3 for Electron - Database stored in user's app data directory - Automatic migration from IndexedDB (if applicable) ### Single Instance Protection - File-based locking prevents concurrent database access - Automatic cleanup on app exit - Graceful handling of lock conflicts ## Security Features ### Content Security Policy - Strict CSP in production builds - Development mode allows localhost connections - Automatic configuration based on build mode ### Auto-Updater - Disabled in development mode - Production builds check for updates automatically - AppImage builds skip update checks ## Troubleshooting ### Common Issues #### Build Failures ```bash # Clean and rebuild npm run clean:electron npm run build:electron:dev ``` #### Native Module Issues ```bash # Rebuild native modules cd electron npm run electron:rebuild ``` #### Single Instance Conflicts - Ensure no other TimeSafari instances are running - Check for orphaned processes: `ps aux | grep electron` - Restart system if necessary #### Database Issues - Check app data directory permissions - Verify SQLite database integrity - Clear app data if corrupted ### Debug Mode ```bash # Enable debug logging DEBUG=* npm run build:electron:dev ``` ## File Structure ``` electron/ ├── src/ │ ├── index.ts # Main process entry point │ ├── preload.ts # Preload script │ └── setup.ts # App setup and configuration ├── assets/ # App icons and resources ├── package.json # Electron-specific dependencies ├── electron-builder.config.json # Build configuration └── tsconfig.json # TypeScript configuration ``` ## Development Workflow 1. **Start Development** ```bash npm run build:electron:dev ``` 2. **Make Changes** - Edit source files in `src/` - Changes auto-reload in development 3. **Test Build** ```bash npm run build:electron:test ``` 4. **Production Build** ```bash npm run build:electron:prod ``` ## Performance Considerations ### Memory Usage - Monitor renderer process memory - Implement proper cleanup in components - Use efficient data structures ### Startup Time - Lazy load non-critical modules - Optimize database initialization - Minimize synchronous operations ### Database Performance - Use transactions for bulk operations - Implement proper indexing - Monitor query performance ## Security Checklist - [ ] Content Security Policy configured - [ ] Auto-updater properly configured - [ ] Single instance enforcement active - [ ] Database access properly secured - [ ] IPC handlers validate input - [ ] File system access restricted - [ ] Network requests validated ## Deployment ### Distribution - Windows: `.exe` installer - macOS: `.dmg` disk image - Linux: `.AppImage` or `.deb` package ### Code Signing - Windows: Authenticode certificate - macOS: Developer ID certificate - Linux: GPG signing (optional) ### Auto-Updates - Configured for production builds - Disabled for development and AppImage - Handles update failures gracefully --- **Last Updated**: 2025-01-10 **Version**: 1.0.3-beta **Status**: Production Ready