# 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 