Browse Source
- Updated electron-builder.config.json with proper TimeSafari metadata - Added Linux package support (AppImage, deb, rpm) - Created build-packages.sh script for easy package building - Added npm scripts for building from project root - Created comprehensive README-BUILDING.md documentation - Fixed package.json metadata (author, homepage, repository) - Added maintainer information for Linux packages Features: - AppImage: Portable, no installation required (~145MB) - Debian package: System integration via package manager (~96MB) - RPM package: Support for RPM-based distributions - Build scripts support individual or all package types Usage: - npm run electron:build (all packages) - npm run electron:build:appimage (AppImage only) - npm run electron:build:deb (Debian package only) - cd electron && ./build-packages.sh [type]streamline-attempt
Matthew Raymer
4 weeks ago
5 changed files with 357 additions and 10 deletions
@ -0,0 +1,251 @@ |
|||
# 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! 🚀** |
|||
@ -0,0 +1,56 @@ |
|||
#!/bin/bash |
|||
|
|||
# TimeSafari Electron Build Script |
|||
# Usage: ./build-packages.sh [pack|appimage|deb|rpm|all] |
|||
|
|||
set -e |
|||
|
|||
echo "🚀 TimeSafari Electron Build Script" |
|||
echo "==================================" |
|||
|
|||
# Build TypeScript and rebuild native modules |
|||
echo "📦 Building TypeScript and native modules..." |
|||
npm run build |
|||
|
|||
BUILD_TYPE="${1:-all}" |
|||
|
|||
case "$BUILD_TYPE" in |
|||
"pack") |
|||
echo "📦 Creating unpacked build..." |
|||
npx electron-builder build --dir -c ./electron-builder.config.json |
|||
;; |
|||
"appimage") |
|||
echo "📦 Creating AppImage..." |
|||
npx electron-builder build --linux AppImage -c ./electron-builder.config.json |
|||
;; |
|||
"deb") |
|||
echo "📦 Creating Debian package..." |
|||
npx electron-builder build --linux deb -c ./electron-builder.config.json |
|||
;; |
|||
"rpm") |
|||
echo "📦 Creating RPM package..." |
|||
if ! command -v rpmbuild &> /dev/null; then |
|||
echo "⚠️ rpmbuild not found. Install with: sudo pacman -S rpm-tools" |
|||
exit 1 |
|||
fi |
|||
npx electron-builder build --linux rpm -c ./electron-builder.config.json |
|||
;; |
|||
"all") |
|||
echo "📦 Creating all Linux packages..." |
|||
npx electron-builder build --linux -c ./electron-builder.config.json |
|||
;; |
|||
*) |
|||
echo "❌ Unknown build type: $BUILD_TYPE" |
|||
echo "Usage: $0 [pack|appimage|deb|rpm|all]" |
|||
exit 1 |
|||
;; |
|||
esac |
|||
|
|||
echo "" |
|||
echo "✅ Build completed successfully!" |
|||
echo "📁 Output files in: ./dist/" |
|||
echo "" |
|||
echo "📦 Available packages:" |
|||
ls -la dist/ | grep -E '\.(AppImage|deb|rpm)$' || echo " No packages found" |
|||
echo "" |
|||
echo "🎉 Ready to distribute!" |
|||
Loading…
Reference in new issue