crowd-funder-from-jason/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
```bash
# 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
```bash
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

```bash
# 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

```bash
# 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

```bash
# 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
```bash
# 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`:
```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
```bash
# Clear cache and rebuild
npm run build
```

#### 2. Missing Dependencies
```bash
# Install system dependencies (Arch Linux)
sudo pacman -S base-devel python

# Install Node dependencies
npm install
```

#### 3. RPM Build Fails
```bash
# 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:
```bash
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! 🚀**