crowd-funder-from-jason/docs/electron-build-scripts.md

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:

# 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

# 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

# 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

# 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

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

# Test with production build (runs app directly)
npm run build:electron:test

Distribution Workflow

# 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

# 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

# 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

# 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