# Electron Build Scripts Guide **Author**: Matthew Raymer **Date**: 2025-07-11 **Status**: **ACTIVE** - Production Ready ## Overview This document clarifies the difference between Electron build scripts that create executable packages versus those that run the app directly. ## Script Categories ### 🚀 **Development Scripts (Run App Directly)** These scripts build the app and then run it immediately for development: ```bash # Development mode - runs app directly npm run build:electron:dev # Test mode - runs app directly npm run build:electron:test # Production mode - runs app directly npm run build:electron:prod ``` ### 📦 **Package Build Scripts (Create Executables)** These scripts build executable packages that can be distributed and run by users: #### **Platform-Specific Executables** ```bash # Windows executable (.exe) npm run build:electron:windows npm run build:electron:windows:dev npm run build:electron:windows:test npm run build:electron:windows:prod # macOS app bundle (.app) npm run build:electron:mac npm run build:electron:mac:dev npm run build:electron:mac:test npm run build:electron:mac:prod # Linux executable npm run build:electron:linux npm run build:electron:linux:dev npm run build:electron:linux:test npm run build:electron:linux:prod ``` #### **Package Formats** ```bash # Linux AppImage (portable executable) npm run build:electron:appimage npm run build:electron:appimage:dev npm run build:electron:appimage:test npm run build:electron:appimage:prod # Linux DEB package (installable) npm run build:electron:deb npm run build:electron:deb:dev npm run build:electron:deb:test npm run build:electron:deb:prod # macOS DMG package (installable) npm run build:electron:dmg npm run build:electron:dmg:dev npm run build:electron:dmg:test npm run build:electron:dmg:prod ``` ## Output Locations ### **Development Scripts** - Run the app directly in development mode - No files created for distribution - App runs immediately after build ### **Package Scripts** - Create executable files in `electron/dist/` - Files can be distributed to users - Users can run the executables by hand #### **Package Output Examples** ```bash # AppImage electron/dist/TimeSafari-1.0.3-beta.AppImage # DEB package electron/dist/TimeSafari_1.0.3-beta_amd64.deb # DMG package electron/dist/TimeSafari-1.0.3-beta.dmg # Windows executable electron/dist/TimeSafari Setup 1.0.3-beta.exe ``` ## Usage Examples ### **Development Workflow** ```bash # Start development (runs app directly) npm run build:electron:dev # Test with production build (runs app directly) npm run build:electron:test ``` ### **Distribution Workflow** ```bash # Build AppImage for Linux distribution npm run build:electron:appimage:prod # Build DMG for macOS distribution npm run build:electron:dmg:prod # Build Windows installer npm run build:electron:windows:prod ``` ### **Testing Packages** ```bash # Build test version of AppImage npm run build:electron:appimage:test # Test the generated executable ./electron/dist/TimeSafari-1.0.3-beta.AppImage ``` ## Key Differences | Script Type | Purpose | Output | User Action | |-------------|---------|--------|-------------| | Development | Run app directly | None | App starts automatically | | Package | Create executable | `electron/dist/` | User runs executable by hand | ## Best Practices ### **For Development** - Use `npm run build:electron:dev` for daily development - Use `npm run build:electron:test` for testing production builds - App runs immediately after build ### **For Distribution** - Use `npm run build:electron:*:prod` for production packages - Test packages before distribution - Users install/run the generated executables ### **For Testing** - Use `npm run build:electron:*:test` for test packages - Verify executables work on target platforms - Test installation and uninstallation ## Troubleshooting ### **Package Build Issues** ```bash # Check if package was created ls -la electron/dist/ # Verify package integrity file electron/dist/*.AppImage file electron/dist/*.deb file electron/dist/*.dmg ``` ### **Development Issues** ```bash # Clean and rebuild npm run clean:electron npm run build:electron:dev ``` --- **Last Updated**: 2025-07-11 **Version**: 1.0.3-beta **Status**: Production Ready