6.0 KiB

Raw Blame History

TimeSafari Electron Build Guide

Author: Matthew Raymer
Date: 2025-07-11
Status: ACTIVE - Production Ready

Overview

This guide covers building and running the TimeSafari Electron application for desktop platforms (Windows, macOS, Linux).

Prerequisites

Node.js 18+ and npm
TypeScript
Electron Builder
Platform-specific build tools (see below)

Quick Start

Development Mode

# Start development server
npm run build:electron:dev

# Or manually
cd electron
npm run electron:start

Production Builds

# Build for current platform
npm run build:electron:prod

# Platform-specific builds
npm run build:electron:windows
npm run build:electron:mac
npm run build:electron:linux

# Package-specific builds
npm run build:electron:appimage  # Linux AppImage
npm run build:electron:dmg       # macOS DMG installer
npm run build:electron:deb       # Linux DEB package

Single Instance Enforcement

The Electron app enforces single instance operation to prevent database conflicts and resource contention:

Implementation

Uses Electron's built-in app.requestSingleInstanceLock()
Second instances exit immediately with user-friendly message
Existing instance focuses and shows informational dialog

Behavior

First instance: Starts normally and acquires lock
Second instance: Detects existing instance, exits immediately
User experience: Clear messaging about single instance requirement

Benefits

Prevents database corruption from concurrent access
Avoids resource conflicts
Maintains data integrity
User-friendly error handling

Build Configuration

Environment Modes

# Development (default)
npm run build:electron:dev

# Testing
npm run build:electron:test

# Production
npm run build:electron:prod

Platform-Specific Builds

# Windows
npm run build:electron:windows:dev
npm run build:electron:windows:test
npm run build:electron:windows:prod

# macOS
npm run build:electron:mac:dev
npm run build:electron:mac:test
npm run build:electron:mac:prod

# Linux
npm run build:electron:linux:dev
npm run build:electron:linux:test
npm run build:electron:linux:prod

Package Types

# Linux AppImage
npm run build:electron:appimage:dev
npm run build:electron:appimage:test
npm run build:electron:appimage:prod

# macOS DMG
npm run build:electron:dmg:dev
npm run build:electron:dmg:test
npm run build:electron:dmg:prod

# Linux DEB
npm run build:electron:deb:dev
npm run build:electron:deb:test
npm run build:electron:deb:prod

Platform-Specific Requirements

Windows

Windows 10+ (64-bit)
Visual Studio Build Tools (for native modules)

macOS

macOS 10.15+ (Catalina)
Xcode Command Line Tools
Code signing certificate (for distribution)

Linux

Ubuntu 18.04+ / Debian 10+ / CentOS 7+
Development headers for native modules

Database Configuration

SQLite Integration

Uses native Node.js SQLite3 for Electron
Database stored in user's app data directory
Automatic migration from IndexedDB (if applicable)

Single Instance Protection

File-based locking prevents concurrent database access
Automatic cleanup on app exit
Graceful handling of lock conflicts

Security Features

Content Security Policy

Strict CSP in production builds
Development mode allows localhost connections
Automatic configuration based on build mode

Auto-Updater

Disabled in development mode
Production builds check for updates automatically
AppImage builds skip update checks

Troubleshooting

Common Issues

Build Failures

# Clean and rebuild
npm run clean:electron
npm run build:electron:dev

Native Module Issues

# Rebuild native modules
cd electron
npm run electron:rebuild

Single Instance Conflicts

Ensure no other TimeSafari instances are running
Check for orphaned processes: ps aux | grep electron
Restart system if necessary

Database Issues

Check app data directory permissions
Verify SQLite database integrity
Clear app data if corrupted

Debug Mode

# Enable debug logging
DEBUG=* npm run build:electron:dev

File Structure

electron/
├── src/
│   ├── index.ts              # Main process entry point
│   ├── preload.ts            # Preload script
│   └── setup.ts              # App setup and configuration
├── assets/                   # App icons and resources
├── package.json              # Electron-specific dependencies
├── electron-builder.config.json  # Build configuration
└── tsconfig.json            # TypeScript configuration

Development Workflow

Start Development
```
npm run build:electron:dev
```
Make Changes
- Edit source files in src/
- Changes auto-reload in development
Test Build
```
npm run build:electron:test
```
Production Build
```
npm run build:electron:prod
```

Performance Considerations

Memory Usage

Monitor renderer process memory
Implement proper cleanup in components
Use efficient data structures

Startup Time

Lazy load non-critical modules
Optimize database initialization
Minimize synchronous operations

Database Performance

Use transactions for bulk operations
Implement proper indexing
Monitor query performance

Security Checklist

Content Security Policy configured
Auto-updater properly configured
Single instance enforcement active
Database access properly secured
IPC handlers validate input
File system access restricted
Network requests validated

Deployment

Distribution

Windows: .exe installer
macOS: .dmg disk image
Linux: .AppImage or .deb package

Code Signing

Windows: Authenticode certificate
macOS: Developer ID certificate
Linux: GPG signing (optional)

Auto-Updates

Configured for production builds
Disabled for development and AppImage
Handles update failures gracefully

Last Updated: 2025-07-11
Version: 1.0.3-beta
Status: Production Ready

6.0 KiB Raw Blame History