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

Building TimeSafari

This guide explains how to build TimeSafari for different platforms.

Prerequisites

For a quick dev environment setup, use pkgx.

• 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

Forks

If you have forked this to make your own app, you'll want to customize the iOS & Android files. You can either edit existing ones, or you can remove the ios and android directories and regenerate them before the npx cap sync step in each setup.

npx cap add android
npx cap add ios

You'll also want to edit the deep link configuration.

Initial Setup

1. Clone the repository:

   git clone [repository-url]
   cd TimeSafari
   

2. Install dependencies:

   npm install
   

Web Build

To build for web deployment:

1. Run the production build:

   npm run build
   

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

3. To test the production build locally:

   npm run serve
   

Desktop Build (Electron)

Building for Linux

1. Build the electron app in production mode:

   npm run build:electron-prod
   

2. Package the Electron app for Linux:

   # 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

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

• DEB: Install and run

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

Development Testing

For testing the Electron build before packaging:

# 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:

   npm run build:capacitor
   

2. Update iOS project with latest build:

   npx cap sync ios
   

3. Copy the assets:

   mkdir -p ios/App/App/Assets.xcassets/AppIcon.appiconset
   npx capacitor-assets generate --ios
   

4. Open the project in Xcode:

   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:

   rm -rf dist
   npm run build:web
   npm run build:capacitor
   

2. Update Android project with latest build:

   npx cap sync android
   

3. Copy the assets

   npx capacitor-assets generate --android
   

4. Open the project in Android Studio:

   npx cap open android
   

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

Building Android from the console

cd android
./gradlew clean
./gradlew build -Dlint.baselines.continue=true
cd ..
npx cap run android

... or, to create the aab file, bundle instead of build:

./gradlew bundle -Dlint.baselines.continue=true

Configuring Android for deep links

You must add the following intent filter to the android/app/src/main/AndroidManifest.xml file:

            <intent-filter android:autoVerify="true">
               <action android:name="android.intent.action.VIEW" />
               <category android:name="android.intent.category.DEFAULT" />
               <category android:name="android.intent.category.BROWSABLE" />
               <data android:scheme="timesafari" />
            </intent-filter>

You must also add the following to the android/app/build.gradle file:

android {
   // ... existing config ...

   lintOptions {
      disable 'UnsanitizedFilenameFromContentProvider'
      abortOnError false
      baseline file("lint-baseline.xml")
      
      // Ignore Capacitor module issues
      ignore 'DefaultLocale'
      ignore 'UnsanitizedFilenameFromContentProvider'
      ignore 'LintBaseline'
      ignore 'LintBaselineFixed'
   }
}

Modify /android/build.gradle to use a stable version of AGP and make sure Kotlin version is compatible.

buildscript {
   repositories {
      google()
      mavenCentral()
   }
   dependencies {
      // Use a stable version of AGP
      classpath 'com.android.tools.build:gradle:8.1.0'
      
      // Make sure Kotlin version is compatible
      classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0"
   }
}

allprojects {
   repositories {
      google()
      mavenCentral()
   }
}

// Add this to handle version conflicts
configurations.all {
   resolutionStrategy {
      force 'org.jetbrains.kotlin:kotlin-stdlib:1.8.0'
      force 'org.jetbrains.kotlin:kotlin-stdlib-common:1.8.0'
   }
}

PyWebView Desktop Build

Prerequisites for PyWebView

• Python 3.8 or higher

• pip (Python package manager)

• virtualenv (recommended)

• System dependencies:

  # 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):

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

2. Install Python dependencies:

   pip install -r requirements.txt
   

Troubleshooting

If encountering PyInstaller version errors:

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

Development of PyWebView

1. Start the PyWebView development build:

   npm run pywebview:dev
   

Building for Distribution

Linux

npm run pywebview:package-linux

The packaged application will be in dist/TimeSafari

Windows

npm run pywebview:package-win

The packaged application will be in dist/TimeSafari

macOS

npm run pywebview:package-mac

The packaged application will be in dist/TimeSafari

Testing

Run all tests (requires XCode and Android Studio/device):

npm run test:all

See TESTING.md for more details.

Linting

Check code style:

npm run lint

Fix code style issues:

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:

   git tag <VERSION_TAG>
   git push origin <VERSION_TAG>
   

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

Test Server

# 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

# 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

List all installed packages

adb shell pm list packages | grep timesafari

Force stop the app (if it's running)

adb shell am force-stop app.timesafari

Clear app data (if you don't want to fully uninstall)

adb shell pm clear app.timesafari

Uninstall for all users

adb shell pm uninstall -k --user 0 app.timesafari

Check if app is installed

adb shell pm path app.timesafari