This guide explains how to build TimeSafari for different platforms using our unified build scripts.
This guide explains how to build TimeSafari for different platforms.
## Prerequisites
@ -9,54 +9,7 @@ For a quick dev environment setup, use [pkgx](https://pkgx.dev).
- Node.js (LTS version recommended)
- npm (comes with Node.js)
- Git
- For mobile builds: Android Studio (Android) or Xcode (iOS)
- For desktop builds: Capacitor Electron platform
## Unified Build Scripts
TimeSafari now uses unified build scripts that automatically handle environment variables, logging, error handling, and timing. All scripts are located in the `scripts/` directory and use a common utilities library.
### Script Features
- **Automatic Environment Setup**: Each script sets the correct environment variables for its build type
- **Rich Logging**: Colored, timestamped output with different log levels
- **Error Handling**: Proper exit codes and graceful failure recovery
- **Timing**: Automatic execution time tracking for each step
- **Validation**: Checks for required dependencies and files
- **CLI Options**: `--help`, `--verbose`, `--env` flags for all scripts
### Available Scripts
| Script | Purpose | Command |
|--------|---------|---------|
| `capacitor-dev.sh` | Capacitor development | `./scripts/capacitor-dev.sh` |
You'll likely want to use test locations for the Endorser & image & partner servers; see "DEFAULT_ENDORSER_API_SERVER" & "DEFAULT_IMAGE_API_SERVER" & "DEFAULT_PARTNER_API_SERVER" below.
```bash
npm install -g @capacitor/cli
```
2. Add Electron platform:
```bash
npx cap add electron
npm run serve
```
### Development
For development with automatic environment setup:
```bash
# Build web assets
npm run build:capacitor
# Sync with Capacitor
npx cap sync electron
# Open in Electron
npx cap open electron
```
### Production Build
For production builds:
### Compile and minify for test & production
```bash
# Build web assets
npm run build:capacitor
* If there are DB changes: before updating the test server, open browser(s) with current version to test DB migrations.
# Sync with Capacitor
npx cap sync electron
* `npx prettier --write ./sw_scripts/`
# Build Electron app
npx cap build electron
```
* Update the ClickUp tasks & CHANGELOG.md & the version in package.json, run `npm install`.
### Packaging
Capacitor Electron uses electron-builder for packaging. Configure the build in `capacitor.config.json`:
```json
{
"plugins": {
"ElectronBuilder": {
"buildOptions": {
"appId": "app.timesafari.app",
"productName": "TimeSafari",
"directories": {
"output": "dist-electron-packages"
},
"files": [
"dist/**/*",
"electron/**/*"
],
"linux": {
"target": ["AppImage", "deb"],
"category": "Office"
},
"mac": {
"target": ["dmg", "zip"],
"category": "public.app-category.productivity"
},
"win": {
"target": ["nsis", "portable"]
}
}
}
}
}
```
### Running the Packaged App
* Run a build to make sure package-lock version is updated, linting works, etc: `npm install && npm run build`
- **Linux**: AppImage files are self-contained executables
- **macOS**: `.app` bundles can be dragged to Applications folder
- **Windows**: `.exe` installers or portable executables
## Mobile Builds (Capacitor)
### Android Build
* Commit everything (since the commit hash is used the app).
Prerequisites: Android Studio with Java SDK installed
* Put the commit hash in the changelog (which will help you remember to bump the version in the step later).
#### Complete Build Process
* Tag with the new version, [online](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa/releases) or `git tag 1.0.2 && git push origin 1.0.2`.
Use the unified Android build script:
* For test, build the app (because test server is not yet set up to build):
1. Choose Product -> Destination -> Any iOS Device
2. Choose Product -> Archive
3. Click Distribute -> App Store Connect
4. In App Store Connect, add the build to the distribution
(The plain `npm run build:web` uses the .env.production file.)
## Testing
* Back up the time-safari/dist folder & deploy: `mv time-safari/dist time-safari-dist-prev-2 && mv crowd-funder-for-time-pwa/dist time-safari/`
### Complete Test Suite
Run all tests with automatic environment setup:
```bash
./scripts/test-all.sh
```
### Mobile Tests
Run mobile-specific tests:
```bash
./scripts/test-mobile.sh
```
### Environment Testing
Test environment variable handling:
```bash
./scripts/test-env.sh
```
* Record the new hash in the changelog. Edit package.json to increment version & add "-beta", `npm install`, commit, and push. Also record what version is on production.
## Docker Deployment
@ -556,111 +202,280 @@ docker run -d \
- Check nginx configuration
- Verify caching settings
## Configuration
## Desktop Build (Electron)
### Deep Links
### Linux Build
#### Android Configuration
1. Build the electron app in production mode:
You must add the following intent filter to the `android/app/src/main/AndroidManifest.xml` file:
Note: When using `timesafari://` scheme, you may encounter build errors about missing http(s) scheme and host attributes. This is expected for custom URL schemes.
3. The packaged applications will be in `dist-electron-packages/`:
The same Capacitor plugins work across all platforms:
```bash
npx cap open ios
```
6. Use Xcode to build and run on simulator or device.
* Select Product -> Destination with some Simulator version. Then click the run arrow.
7. Release
* Someday: Under "General" we want to rename a bunch of things to "Time Safari"
* Choose Product -> Destination -> Any iOS Device
* Choose Product -> Archive
* This will trigger a build and take time, needing user's "login" keychain password (user's login password), repeatedly.
* If it fails with `building for 'iOS', but linking in dylib (.../.pkgx/zlib.net/v1.3.0/lib/libz.1.3.dylib) built for 'macOS'` then run XCode outside that terminal (ie. not with `npx cap open ios`).
* Click Distribute -> App Store Connect
* In AppStoreConnect, add the build to the distribution: remove the current build with the "-" when you hover over it, then "Add Build" with the new build.
* May have to go to App Review, click Submission, then hover over the build and click "-".
* It can take 15 minutes for the build to show up in the list of builds.
* You'll probably have to "Manage" something about encryption, disallowed in France.
* Then "Save" and "Add to Review" and "Resubmit to App Review".
### Android Build
Prerequisites: Android Studio with Java SDK installed
1. Build the web assets:
```bash
rm -rf dist
npm run build:web
npm run build:capacitor
```
2. Update Android project with latest build:
```bash
npx cap sync android
```
3. Copy the assets
```bash
npx capacitor-assets generate --android
```
4. Bump version to match iOS & package.json: android/app/build.gradle
5. Open the project in Android Studio:
```bash
npx cap open android
```
6. Use Android Studio to build and run on emulator or device.
## Android Build from the console
```bash
cd android
./gradlew clean
./gradlew build -Dlint.baselines.continue=true
cd -
```
... or, to create the `aab` file, `bundle` instead of `build`:
* Setup by adding the app/gradle.properties.secrets file (see properties at top of app/build.gradle) and the app/time-safari-upload-key-pkcs12.jks file
* In app/build.gradle, bump the versionCode and maybe the versionName
... though when we tried that most recently it failed to 'build' the APK with: http(s) scheme and host attribute are missing, but are required for Android App Links [AppLinkUrlError]
Matthew Raymer
1 week ago