forked from jsnbuchanan/crowd-funder-for-time-pwa
db5da0cdfc
- Create logical sub-folder classification for all documentation - Organize 91 migration files into component-specific folders - Separate user guides, build system, migration, and development docs - Maintain maximum 7 items per folder for easy navigation - Add comprehensive README and reorganization summary - Ensure all changes tracked in git with proper versioning Structure: - user-guides/ (3 items): user-facing documentation - build-system/ (3 items): core, platforms, automation - migration/ (6 items): assessments, testing, templates - development/ (4 items): tools and standards - architecture/, testing/, examples/ (ready for future docs) Total: 24 folders created, all within 7-item limits
181 lines
4.2 KiB
Markdown
181 lines
4.2 KiB
Markdown
# 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 |