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

# Building TimeSafari

This guide explains how to build TimeSafari for different platforms.

## Prerequisites

- Node.js (LTS version recommended)
- npm (comes with Node.js)
- Git
- For iOS builds: macOS with Xcode installed
- For Android builds: Android Studio with SDK installed
- For desktop builds: Additional build tools based on your OS

## Initial Setup

1. Clone the repository:

   ```bash
   git clone [repository-url]
   cd TimeSafari
   ```

2. Install dependencies:

   ```bash
   npm install
   ```

## Web Build

To build for web deployment:

1. Run the production build:

   ```bash
   npm run build
   ```

2. The built files will be in the `dist` directory.

3. To test the production build locally:

   ```bash
   npm run serve
   ```

## Desktop Build (Electron)

### Building for Linux

1. Build the electron app in production mode:

   ```bash
   npm run build:electron-prod
   ```

2. Package the Electron app for Linux:

   ```bash
   # For AppImage (recommended)
   npm run electron:build-linux

   # For .deb package
   npm run electron:build-linux-deb
   ```

3. The packaged applications will be in `dist-electron-packages/`:
   - AppImage: `dist-electron-packages/TimeSafari-x.x.x.AppImage`
   - DEB: `dist-electron-packages/timesafari_x.x.x_amd64.deb`

### Running the Packaged App

- AppImage: Make executable and run

  ```bash
  chmod +x dist-electron-packages/TimeSafari-*.AppImage
  ./dist-electron-packages/TimeSafari-*.AppImage
  ```

- DEB: Install and run

  ```bash
  sudo dpkg -i dist-electron-packages/timesafari_*_amd64.deb
  timesafari
  ```

### Development Testing

For testing the Electron build before packaging:

```bash
# Build and run in development mode (includes DevTools)
npm run electron:dev

# Build in production mode and test
npm run build:electron-prod && npm run electron:start
```

## Mobile Builds (Capacitor)

### iOS Build

Prerequisites: macOS with Xcode installed

1. Build the web assets:

   ```bash
   npm run build -- --mode capacitor
   ```

2. Add iOS platform if not already added:

   ```bash
   npx cap add ios
   ```

3. Update iOS project with latest build:

   ```bash
   npx cap sync ios
   ```

4. Open the project in Xcode:

   ```bash
   npx cap open ios
   ```

5. Use Xcode to build and run on simulator or device.

### Android Build

Prerequisites: Android Studio with SDK installed

1. Build the web assets:

   ```bash
   npm run build -- --mode capacitor
   ```

2. Add Android platform if not already added:

   ```bash
   npx cap add android
   ```

3. Update Android project with latest build:

   ```bash
   npx cap sync android
   ```

4. Open the project in Android Studio:

   ```bash
   npx cap open android
   ```

5. Use Android Studio to build and run on emulator or device.

## Development

To run the application in development mode:

1. Start the development server:

   ```bash
   npm run dev
   ```

## PyWebView Desktop Build

### Prerequisites for PyWebView

- Python 3.8 or higher
- pip (Python package manager)
- virtualenv (recommended)
- System dependencies:

  ```bash
  # For Ubuntu/Debian
  sudo apt-get install python3-webview
  # or
  sudo apt-get install python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-webkit2-4.0

  # For Arch Linux
  sudo pacman -S webkit2gtk python-gobject python-cairo

  # For Fedora
  sudo dnf install python3-webview
  # or
  sudo dnf install python3-gobject python3-cairo webkit2gtk3
  ```

### Setup

1. Create and activate a virtual environment (recommended):

   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Linux/macOS
   # or
   .venv\Scripts\activate     # On Windows
   ```

2. Install Python dependencies:

   ```bash
   pip install -r requirements.txt
   ```

### Troubleshooting

If encountering PyInstaller version errors:

```bash
# Try installing the latest stable version
pip install --upgrade pyinstaller
```

### Development of PyWebView

1. Start the PyWebView development build:

   ```bash
   npm run pywebview:dev
   ```

### Building for Distribution

#### Linux

```bash
npm run pywebview:package-linux
```

The packaged application will be in `dist/TimeSafari`

#### Windows

```bash
npm run pywebview:package-win
```

The packaged application will be in `dist/TimeSafari`

#### macOS

```bash
npm run pywebview:package-mac
```

The packaged application will be in `dist/TimeSafari`

## Testing

Run local tests:

```bash
npm run test-local
```

Run all tests (includes building):

```bash
npm run test-all
```

## Linting

Check code style:

```bash
npm run lint
```

Fix code style issues:

```bash
npm run lint-fix
```

## Environment Configuration

See `.env.*` files for configuration.

## Notes

- The application uses PWA (Progressive Web App) features for web builds
- Electron builds disable PWA features automatically
- Build output directories:
  - Web: `dist/`
  - Electron: `dist-electron/`
  - Capacitor: `dist-capacitor/`

## Deployment

### Version Management

1. Update CHANGELOG.md with new changes
2. Update version in package.json
3. Commit changes and tag release:

   ```bash
   git tag <VERSION_TAG>
   git push origin <VERSION_TAG>
   ```

4. After deployment, update package.json with next version + "-beta"

### Test Server

```bash
# Build using staging environment
npm run build -- --mode staging

# Deploy to test server
rsync -azvu -e "ssh -i ~/.ssh/<YOUR_KEY>" dist ubuntutest@test.timesafari.app:time-safari/
```

### Production Server

```bash
# On the production server:
pkgx +npm sh
cd crowd-funder-for-time-pwa
git checkout master && git pull
git checkout <VERSION_TAG>
npm install
npm run build
cd -

# Backup and deploy
mv time-safari/dist time-safari-dist-prev.0 && mv crowd-funder-for-time-pwa/dist time-safari/
```

## Troubleshooting Builds

### Common Build Issues

1. **Missing Environment Variables**
   - Check that all required variables are set in your .env file
   - For development, ensure local services are running on correct ports

2. **Electron Build Failures**
   - Verify Node.js version compatibility
   - Check that all required dependencies are installed
   - Ensure proper paths in electron/main.js

3. **Mobile Build Issues**
   - For iOS: Xcode command line tools must be installed
   - For Android: Correct SDK version must be installed
   - Check Capacitor configuration in capacitor.config.ts