forked from jsnbuchanan/crowd-funder-for-time-pwa

Files

Matthew Raymer db5da0cdfc docs: reorganize documentation structure with 7-item folder limits

- 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

2025-07-22 09:18:30 +00:00

4.2 KiB

Raw Blame History

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

4.2 KiB Raw Blame History