crowd-funder-for-time-pwa/electron/README-BUILDING.md

Building TimeSafari Electron App

This guide explains how to build distributable packages for the TimeSafari Electron desktop application.

Quick Start

From Project Root

# Build all Linux packages (AppImage, deb)
npm run electron:build

# Build specific package types
npm run electron:build:appimage  # AppImage only
npm run electron:build:deb       # Debian package only

From Electron Directory

cd electron

# Build all packages
./build-packages.sh

# Build specific types
./build-packages.sh appimage
./build-packages.sh deb
./build-packages.sh pack    # Unpacked directory (for testing)

Package Types

1. AppImage (Recommended for Linux)

• File: TimeSafari-1.0.0.AppImage
• Size: ~145MB
• Usage: Download and run directly, no installation required
• Distribution: Upload to GitHub releases or website

# Make executable and run
chmod +x TimeSafari-1.0.0.AppImage
./TimeSafari-1.0.0.AppImage

2. Debian Package (.deb)

• File: TimeSafari_1.0.0_amd64.deb
• Size: ~96MB
• Usage: Install via package manager
• Distribution: Upload to repositories or direct download

# Install
sudo dpkg -i TimeSafari_1.0.0_amd64.deb

# Run
timesafari

3. RPM Package (.rpm)

• File: TimeSafari-1.0.0.x86_64.rpm
• Requirements: rpmbuild must be installed
• Usage: Install via package manager

# Install rpmbuild (Arch Linux)
sudo pacman -S rpm-tools

# Build RPM
./build-packages.sh rpm

# Install (on RPM-based systems)
sudo rpm -i TimeSafari-1.0.0.x86_64.rpm

Build Requirements

System Dependencies

• Node.js 18+
• npm or yarn
• Python 3 (for native module compilation)
• Build tools (gcc, make)

Optional Dependencies

• rpmbuild - for RPM packages
• fpm - automatically downloaded by electron-builder

Node Dependencies

All required dependencies are in package.json:

• electron-builder - Main build tool
• better-sqlite3-multiple-ciphers - SQLite with encryption
• Native module compilation tools

Build Process

1. Preparation

# Install dependencies
npm install

# Build TypeScript
npm run build

2. Package Creation

The build process:

1. Compiles TypeScript to JavaScript
2. Rebuilds native modules for Electron
3. Packages the app with electron-builder
4. Creates platform-specific installers

3. Output Location

All built packages are saved to electron/dist/:

dist/
├── TimeSafari-1.0.0.AppImage      # Portable AppImage
├── TimeSafari_1.0.0_amd64.deb     # Debian package
├── TimeSafari-1.0.0.x86_64.rpm    # RPM package (if built)
└── linux-unpacked/                # Unpacked directory

Configuration

App Metadata

App information is configured in electron/package.json:

{
  "name": "TimeSafari",
  "version": "1.0.0",
  "description": "Time Safari - Community building through gifts, gratitude, and collaborative projects",
  "homepage": "https://timesafari.app",
  "author": {
    "name": "Matthew Raymer",
    "email": "matthew@timesafari.app"
  }
}

Build Configuration

Build settings are in electron/electron-builder.config.json:

• Package formats and architectures
• Icons and assets
• Platform-specific settings
• Signing and publishing options

Troubleshooting

Common Issues

1. Native Module Compilation Errors

# Clear cache and rebuild
npm run build

2. Missing Dependencies

# Install system dependencies (Arch Linux)
sudo pacman -S base-devel python

# Install Node dependencies
npm install

3. RPM Build Fails

# Install rpmbuild
sudo pacman -S rpm-tools

# Try building again
./build-packages.sh rpm

4. Large Package Size

The packages are large (~100-150MB) because they include:

• Complete Electron runtime
• Node.js runtime
• SQLite native modules
• Application assets

This is normal for Electron applications.

Debug Mode

For detailed build information:

DEBUG=electron-builder npx electron-builder build

Distribution

GitHub Releases

1. Create a new release on GitHub
2. Upload the built packages as release assets
3. Users can download and install directly

Package Repositories

• Debian/Ubuntu: Upload .deb to repository
• Fedora/CentOS: Upload .rpm to repository
• Arch Linux: Create PKGBUILD for AUR

Direct Download

Host the packages on your website for direct download.

Cross-Platform Building

Current Support

• Linux: Full support (AppImage, deb, rpm)
• Windows: Configured but requires Windows build environment
• macOS: Configured but requires macOS build environment

Building for Other Platforms

To build for Windows or macOS, you need:

• The target platform's build environment
• Platform-specific signing certificates
• Updated build configuration

Security Considerations

Code Signing

For production releases, consider code signing:

• Linux: Not required but recommended
• Windows: Required for Windows SmartScreen
• macOS: Required for Gatekeeper

Package Integrity

• Verify package checksums
• Use HTTPS for distribution
• Consider GPG signatures for packages

Performance Tips

Build Optimization

• Use --dir flag for faster development builds
• Cache node_modules between builds
• Use CI/CD for automated builds

Package Size Reduction

• Remove unnecessary dependencies
• Use electron-builder's file filtering
• Consider using electron-updater for delta updates

Support

For build issues:

1. Check the console output for specific errors
2. Verify all dependencies are installed
3. Try cleaning and rebuilding
4. Check electron-builder documentation
5. Open an issue with build logs

---

Happy Building! 🚀