trent_larson
/
crowd-funder-for-time-pwa
4
1
Fork 2
Code Pull Requests 11 Releases 5 Wiki Activity
Browse Source

revert BUILDING to master version

pull/142/head
Matthew Raymer 1 month ago
parent
a16235a0de
commit
df437b2310
1 changed files with 275 additions and 460 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 723
      BUILDING.md

723
BUILDING.md
View File

@ -1,6 +1,6 @@
# Building TimeSafari # Building TimeSafari
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 ## Prerequisites
@ -9,54 +9,7 @@ For a quick dev environment setup, use [pkgx](https://pkgx.dev).
- Node.js (LTS version recommended) - Node.js (LTS version recommended)
- npm (comes with Node.js) - npm (comes with Node.js)
- Git - Git
- For mobile builds: Android Studio (Android) or Xcode (iOS) - For desktop builds: Additional build tools based on your OS
- 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` |
| `capacitor-build.sh` | Capacitor build | `./scripts/build-capacitor.sh` |
| `web-dev.sh` | Web development | `./scripts/web-dev.sh` |
| `web-build.sh` | Web build | `./scripts/build-web.sh` |
### Environment Variables
All scripts automatically set the correct environment variables for their build type:
| Build Type | VITE_PLATFORM | VITE_PWA_ENABLED | VITE_DISABLE_PWA | NODE_ENV |
|------------|---------------|------------------|------------------|----------|
| `capacitor` | capacitor | false | true | - |
| `web` | web | true | false | - |
### CLI Options
All scripts support these options:
```bash
# Show help
./scripts/build-capacitor.sh --help
# Enable verbose logging
./scripts/build-capacitor.sh --verbose
# Show environment variables
./scripts/build-capacitor.sh --env
```
## Forks ## Forks
@ -77,305 +30,287 @@ Install dependencies:
npm install npm install
``` ```
## Package Management ## Web Dev Locally
TimeSafari uses a mixed package management approach, combining npm and JSR (JavaScript Registry) for optimal dependency management. ```bash
npm run dev
```
### JSR Integration ## Web Build for Server
Some packages are installed via JSR for better ESM support and modern TypeScript compatibility: 1. Run the production build:
```bash ```bash
# Install JSR packages rm -rf dist
npx jsr add @nostr/tools npm run build:web
``` ```
### Package Migration History The built files will be in the `dist` directory.
#### nostr-tools → @nostr/tools
**Date**: June 2025 2. To test the production build locally:
**Reason**: Resolved Vite/Rollup build issues with deep imports
**Before** (npm): 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.
```typescript ```bash
import { finalizeEvent } from "nostr-tools/lib/cjs/index.js"; npm run serve
import { accountFromExtendedKey } from "nostr-tools/lib/cjs/nip06.js";
``` ```
**After** (JSR): ### Compile and minify for test & production
```typescript * If there are DB changes: before updating the test server, open browser(s) with current version to test DB migrations.
import { finalizeEvent } from "@nostr/tools";
import { accountFromExtendedKey } from "@nostr/tools/nip06";
```
**Benefits**: * `npx prettier --write ./sw_scripts/`
- ✅ Proper ESM support
- ✅ No deep import issues with Vite/Rollup
- ✅ Better TypeScript compatibility
- ✅ Modern package structure
### Current Package Strategy * Update the ClickUp tasks & CHANGELOG.md & the version in package.json, run `npm install`.
- **npm**: Primary package manager for most dependencies * Run a build to make sure package-lock version is updated, linting works, etc: `npm install && npm run build`
- **JSR**: Used for packages with better ESM support or modern alternatives
- **Mixed approach**: Allows using the best package for each dependency
### When to Use JSR * Commit everything (since the commit hash is used the app).
Consider using JSR for: * Put the commit hash in the changelog (which will help you remember to bump the version in the step later).
- Packages with ESM/CJS compatibility issues in npm
- Modern TypeScript-first packages
- Packages that work better with modern bundlers
- New dependencies where JSR has a better alternative
### Vite Configuration * 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`.
The build system is configured to handle both npm and JSR packages: * For test, build the app (because test server is not yet set up to build):
```typescript ```bash
// vite.config.common.mts TIME_SAFARI_APP_TITLE="TimeSafari_Test" VITE_APP_SERVER=https://test.timesafari.app VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app VITE_DEFAULT_PARTNER_API_SERVER=https://test-partner-api.endorser.ch VITE_DEFAULT_PUSH_SERVER=https://test.timesafari.app VITE_PASSKEYS_ENABLED=true npm run build:web
resolve: {
alias: {
'@nostr/tools': path.resolve(__dirname, 'node_modules/@nostr/tools'),
'@nostr/tools/nip06': path.resolve(__dirname, 'node_modules/@nostr/tools/nip06'),
}
}
``` ```
### Troubleshooting Package Issues ... and transfer to the test server:
1. **Build failures with deep imports** ```bash
- Check if package has ESM/CJS compatibility issues rsync -azvu -e "ssh -i ~/.ssh/..." dist ubuntutest@test.timesafari.app:time-safari
- Consider JSR alternative if available ```
- Update Vite configuration if needed
2. **TypeScript errors** (Let's replace that with a .env.development or .env.staging file.)
- Ensure proper type definitions are available
- Check package exports in package.json
- Verify import paths match package structure
3. **Mixed package manager issues** (Note: The test BVC_MEETUPS_PROJECT_CLAIM_ID does not resolve as a URL because it's only in the test DB and the prod redirect won't redirect there.)
- Keep package.json and node_modules in sync
- Use `npm install` after JSR package additions
- Check for conflicting package versions
## Web Development * For prod, get on the server and run the correct build:
### Local Development ... and log onto the server:
```bash * `pkgx +npm sh`
npm run dev
```
### Web Build for Server * `cd crowd-funder-for-time-pwa && git checkout master && git pull && git checkout 1.0.2 && npm install && npm run build:web && cd -`
1. Run the production build: (The plain `npm run build:web` uses the .env.production file.)
```bash * 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/`
npm run build:web
```
The built files will be in the `dist` directory. * 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.
2. To test the production build locally: ## Docker Deployment
```bash The application can be containerized using Docker for consistent deployment across environments.
npm run serve
``` ### Prerequisites
### Environment Configuration - Docker installed on your system
- Docker Compose (optional, for multi-container setups)
For different environments, create `.env` files: ### Building the Docker Image
```bash 1. Build the Docker image:
# .env.development
VITE_APP_SERVER=https://dev.timesafari.app
VITE_DEFAULT_ENDORSER_API_SERVER=https://dev-api.endorser.ch
VITE_DEFAULT_IMAGE_API_SERVER=https://dev-image-api.timesafari.app
VITE_DEFAULT_PARTNER_API_SERVER=https://dev-partner-api.endorser.ch
VITE_DEFAULT_PUSH_SERVER=https://dev.timesafari.app
VITE_PASSKEYS_ENABLED=true
# .env.production ```bash
VITE_APP_SERVER=https://timesafari.app docker build -t timesafari:latest .
VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch
VITE_DEFAULT_IMAGE_API_SERVER=https://image-api.timesafari.app
VITE_DEFAULT_PARTNER_API_SERVER=https://partner-api.endorser.ch
VITE_DEFAULT_PUSH_SERVER=https://timesafari.app
VITE_PASSKEYS_ENABLED=true
``` ```
## Desktop Build (Capacitor Electron) 2. For development builds with specific environment variables:
### Prerequisites ```bash
docker build --build-arg NODE_ENV=development -t timesafari:dev .
```
1. Install Capacitor CLI: ### Running the Container
1. Run the container:
```bash ```bash
npm install -g @capacitor/cli docker run -d -p 80:80 timesafari:latest
``` ```
2. Add Electron platform: 2. For development with hot-reloading:
```bash ```bash
npx cap add electron docker run -d -p 80:80 -v $(pwd):/app timesafari:dev
``` ```
### Development ### Using Docker Compose
For development with automatic environment setup: Create a `docker-compose.yml` file:
```bash ```yaml
# Build web assets version: '3.8'
npm run build:capacitor services:
timesafari:
build: .
ports:
- "80:80"
environment:
- NODE_ENV=production
restart: unless-stopped
```
# Sync with Capacitor Run with Docker Compose:
npx cap sync electron
# Open in Electron ```bash
npx cap open electron docker-compose up -d
``` ```
### Production Build ### Production Deployment
For production builds: For production deployment, consider the following:
1. Use specific version tags instead of 'latest'
2. Implement health checks
3. Configure proper logging
4. Set up reverse proxy with SSL termination
5. Use Docker secrets for sensitive data
Example production deployment:
```bash ```bash
# Build web assets # Build with specific version
npm run build:capacitor docker build -t timesafari:1.0.0 .
# Sync with Capacitor # Run with production settings
npx cap sync electron docker run -d \
--name timesafari \
# Build Electron app -p 80:80 \
npx cap build electron --restart unless-stopped \
``` -e NODE_ENV=production \
timesafari:1.0.0
### 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 ### Troubleshooting Docker
- **Linux**: AppImage files are self-contained executables 1. **Container fails to start**
- **macOS**: `.app` bundles can be dragged to Applications folder - Check logs: `docker logs <container_id>`
- **Windows**: `.exe` installers or portable executables - Verify port availability
- Check environment variables
## Mobile Builds (Capacitor) 2. **Build fails**
- Ensure all dependencies are in package.json
- Check Dockerfile syntax
- Verify build context
### Android Build 3. **Performance issues**
- Monitor container resources: `docker stats`
- Check nginx configuration
- Verify caching settings
Prerequisites: Android Studio with Java SDK installed ## Desktop Build (Electron)
#### Complete Build Process ### Linux Build
Use the unified Android build script: 1. Build the electron app in production mode:
```bash ```bash
./scripts/build-android.sh npm run build:electron-prod
``` ```
This script automatically: 2. Package the Electron app for Linux:
1. Sets up environment variables for Capacitor
2. Cleans previous builds
3. Builds web assets
4. Builds Capacitor version
5. Cleans and builds Gradle project
6. Syncs with Capacitor
7. Generates assets
8. Opens Android Studio
#### Manual Steps (if needed) ```bash
# For AppImage (recommended)
npm run electron:build-linux
If you need to run individual steps: # 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`
### macOS Build
1. Build the electron app in production mode:
1. Build the web assets:
```bash ```bash
npm run build:web npm run build:web
npm run build:capacitor npm run build:electron
npm run electron:build-mac
``` ```
2. Update Android project: 2. Package the Electron app for macOS:
```bash ```bash
npx cap sync android # For Intel Macs
npm run electron:build-mac
# For Universal build (Intel + Apple Silicon)
npm run electron:build-mac-universal
``` ```
3. Generate assets: 3. The packaged applications will be in `dist-electron-packages/`:
- `.app` bundle: `TimeSafari.app`
- `.dmg` installer: `TimeSafari-x.x.x.dmg`
- `.zip` archive: `TimeSafari-x.x.x-mac.zip`
### Code Signing and Notarization (macOS)
For public distribution on macOS, you need to code sign and notarize your app:
1. Set up environment variables:
```bash ```bash
npx capacitor-assets generate --android export CSC_LINK=/path/to/your/certificate.p12
export CSC_KEY_PASSWORD=your_certificate_password
export APPLE_ID=your_apple_id
export APPLE_ID_PASSWORD=your_app_specific_password
``` ```
4. Open in Android Studio: 2. Build with signing:
```bash ```bash
npx cap open android npm run electron:build-mac
``` ```
#### Console Build ### Running the Packaged App
For building from the console:
- **Linux**:
- AppImage: Make executable and run
```bash ```bash
cd android chmod +x dist-electron-packages/TimeSafari-*.AppImage
./gradlew clean ./dist-electron-packages/TimeSafari-*.AppImage
./gradlew build -Dlint.baselines.continue=true
cd -
``` ```
- DEB: Install and run
For creating an `aab` file:
```bash ```bash
cd android sudo dpkg -i dist-electron-packages/timesafari_*_amd64.deb
./gradlew bundleDebug -Dlint.baselines.continue=true timesafari
cd -
``` ```
For creating a signed release: - **macOS**:
- `.app` bundle: Double-click `TimeSafari.app` in Finder
- `.dmg` installer:
1. Double-click the `.dmg` file
2. Drag the app to your Applications folder
3. Launch from Applications
- `.zip` archive:
1. Extract the `.zip` file
2. Move `TimeSafari.app` to your Applications folder
3. Launch from Applications
Note: If you get a security warning when running the app:
1. Right-click the app
2. Select "Open"
3. Click "Open" in the security dialog
### Development Testing
For testing the Electron build before packaging:
1. Setup signing configuration in `app/gradle.properties.secrets`
2. Add signing key file `app/time-safari-upload-key-pkcs12.jks`
3. Update version in `app/build.gradle`
4. Build release:
```bash ```bash
cd android # Build and run in development mode (includes DevTools)
./gradlew bundleRelease -Dlint.baselines.continue=true npm run electron:dev
cd -
# Build in production mode and test
npm run build:electron-prod && npm run electron:start
``` ```
The `aab` file will be at `app/build/outputs/bundle/release`. ## Mobile Builds (Capacitor)
### iOS Build ### iOS Build
@ -383,184 +318,154 @@ Prerequisites: macOS with Xcode installed
#### First-time iOS Configuration #### First-time iOS Configuration
- Generate certificates inside Xcode - Generate certificates inside XCode.
- Right-click on App and under Signing & Capabilities set the Team
- Right-click on App and under Signing & Capabilities set the Team.
#### Each Release
0. First time (or if dependencies change):
#### Build Process - `pkgx +rubygems.org sh`
- ... and you may have to fix these, especially with pkgx:
```bash
gem_path=$(which gem)
shortened_path="${gem_path:h:h}"
export GEM_HOME=$shortened_path
export GEM_PATH=$shortened_path
```
1. Build the web assets & update ios:
1. Build the web assets & update iOS:
```bash ```bash
rm -rf dist
npm run build:web npm run build:web
npm run build:capacitor npm run build:capacitor
npx cap sync ios npx cap sync ios
``` ```
2. Generate assets: - If that fails with "Could not find..." then look at the "gem_path" instructions above.
3. Copy the assets:
```bash ```bash
# Create required directories # It makes no sense why capacitor-assets will not run without these but it actually changes the contents.
mkdir -p ios/App/App/Assets.xcassets/AppIcon.appiconset mkdir -p ios/App/App/Assets.xcassets/AppIcon.appiconset
echo '{"images":[]}' > ios/App/App/Assets.xcassets/AppIcon.appiconset/Contents.json echo '{"images":[]}' > ios/App/App/Assets.xcassets/AppIcon.appiconset/Contents.json
mkdir -p ios/App/App/Assets.xcassets/Splash.imageset mkdir -p ios/App/App/Assets.xcassets/Splash.imageset
echo '{"images":[]}' > ios/App/App/Assets.xcassets/Splash.imageset/Contents.json echo '{"images":[]}' > ios/App/App/Assets.xcassets/Splash.imageset/Contents.json
# Generate assets
npx capacitor-assets generate --ios npx capacitor-assets generate --ios
``` ```
3. Update version to match Android & package.json: 4. Bump the version to match Android & package.json:
```bash
cd ios/App
xcrun agvtool new-version 35
perl -p -i -e "s/MARKETING_VERSION = .*;/MARKETING_VERSION = 1.0.2;/g" App.xcodeproj/project.pbxproj
cd -
```
4. Open in Xcode:
```bash
npx cap open ios
``` ```
cd ios/App && xcrun agvtool new-version 35 && perl -p -i -e "s/MARKETING_VERSION = .*;/MARKETING_VERSION = 1.0.2;/g" App.xcodeproj/project.pbxproj && cd -
5. Build and run on simulator or device using Xcode # Unfortunately this edits Info.plist directly.
#xcrun agvtool new-marketing-version 0.4.5
#### Release Process
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
## Testing
### Complete Test Suite
Run all tests with automatic environment setup:
```bash
./scripts/test-all.sh
``` ```
### Mobile Tests 5. Open the project in Xcode:
Run mobile-specific tests:
```bash ```bash
./scripts/test-mobile.sh npx cap open ios
``` ```
### Environment Testing 6. Use Xcode to build and run on simulator or device.
Test environment variable handling: * Select Product -> Destination with some Simulator version. Then click the run arrow.
```bash 7. Release
./scripts/test-env.sh
```
## Docker Deployment * 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".
The application can be containerized using Docker for consistent deployment across environments. ### Android Build
### Prerequisites
- Docker installed on your system
- Docker Compose (optional, for multi-container setups)
### Building the Docker Image Prerequisites: Android Studio with Java SDK installed
1. Build the Docker image: 1. Build the web assets:
```bash ```bash
docker build -t timesafari:latest . rm -rf dist
npm run build:web
npm run build:capacitor
``` ```
2. For development builds with specific environment variables: 2. Update Android project with latest build:
```bash ```bash
docker build --build-arg NODE_ENV=development -t timesafari:dev . npx cap sync android
``` ```
### Running the Container 3. Copy the assets
1. Run the container:
```bash ```bash
docker run -d -p 80:80 timesafari:latest npx capacitor-assets generate --android
``` ```
2. For development with hot-reloading: 4. Bump version to match iOS & package.json: android/app/build.gradle
5. Open the project in Android Studio:
```bash ```bash
docker run -d -p 80:80 -v $(pwd):/app timesafari:dev npx cap open android
``` ```
### Using Docker Compose 6. Use Android Studio to build and run on emulator or device.
Create a `docker-compose.yml` file: ## Android Build from the console
```yaml ```bash
version: '3.8' cd android
services: ./gradlew clean
timesafari: ./gradlew build -Dlint.baselines.continue=true
build: . cd -
ports:
- "80:80"
environment:
- NODE_ENV=production
restart: unless-stopped
``` ```
Run with Docker Compose: ... or, to create the `aab` file, `bundle` instead of `build`:
```bash ```bash
docker-compose up -d ./gradlew bundleDebug -Dlint.baselines.continue=true
``` ```
### Production Deployment ... or, to create a signed release:
For production deployment, consider the following:
1. Use specific version tags instead of 'latest'
2. Implement health checks
3. Configure proper logging
4. Set up reverse proxy with SSL termination
5. Use Docker secrets for sensitive data
Example production deployment: * 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
* Then `bundleRelease`:
```bash ```bash
# Build with specific version cd android
docker build -t timesafari:1.0.0 . ./gradlew bundleRelease -Dlint.baselines.continue=true
cd -
# Run with production settings
docker run -d \
--name timesafari \
-p 80:80 \
--restart unless-stopped \
-e NODE_ENV=production \
timesafari:1.0.0
``` ```
### Troubleshooting Docker ... and find your `aab` file at app/build/outputs/bundle/release
1. **Container fails to start**
- Check logs: `docker logs <container_id>`
- Verify port availability
- Check environment variables
2. **Build fails** At play.google.com/console:
- Ensure all dependencies are in package.json
- Check Dockerfile syntax
- Verify build context
3. **Performance issues** - Go to the Testing Track (eg. Closed).
- Monitor container resources: `docker stats` - Click "Create new release".
- Check nginx configuration - Upload the `aab` file.
- Verify caching settings - Hit "Next".
- Save, go to "Publishing Overview" as prompted, and click "Send changes for review".
## Configuration - Note that if you add testers, you have to go to "Publishing Overview" and send those changes or your (closed) testers won't see it.
### Deep Links
#### Android Configuration ## Android Configuration for deep links
You must add the following intent filter to the `android/app/src/main/AndroidManifest.xml` file: You must add the following intent filter to the `android/app/src/main/AndroidManifest.xml` file:
@ -573,94 +478,4 @@ You must add the following intent filter to the `android/app/src/main/AndroidMan
</intent-filter> </intent-filter>
``` ```
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. ... 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]
#### iOS Configuration
For iOS deep links, configure the URL scheme in Xcode:
1. Open the project in Xcode
2. Select your app target
3. Go to Info tab
4. Add URL Types with scheme `timesafari`
## Troubleshooting
### Common Issues
1. **Environment Variables Not Set**
- Use `--env` flag to check current environment: `./scripts/build-capacitor.sh --env`
- Verify `.env` file exists and is properly formatted
- Check script output for environment setup messages
2. **Build Failures**
- Use `--verbose` flag for detailed logging: `./scripts/build-capacitor.sh --verbose`
- Check prerequisites are installed
- Verify all dependencies are installed: `npm install`
3. **Permission Issues**
- Make scripts executable: `chmod +x scripts/*.sh`
- Check file permissions on build directories
4. **Platform-Specific Issues**
- **Android**: Verify Android Studio and SDK are properly configured
- **iOS**: Ensure Xcode and certificates are set up correctly
- **Electron**: Check Capacitor Electron platform installation
### Getting Help
- Check script help: `./scripts/build-capacitor.sh --help`
- Review script documentation in `scripts/README.md`
- Test environment setup: `./scripts/test-env.sh`
- Test common utilities: `./scripts/test-common.sh`
### Platform Support Matrix
| Platform | Mode | PWA Enabled | Native Features | Notes |
|----------|------|-------------|-----------------|-------|
| `web` | web | true | false | Standard web browser |
| `capacitor` | capacitor | false | true | Mobile app (iOS/Android) |
| `electron` | capacitor | false | true | Desktop app (via Capacitor Electron) |
## Platform Service Architecture
TimeSafari uses a unified platform service architecture that works across all platforms:
### Platform Detection
The `CapacitorPlatformService` automatically detects the platform and adjusts capabilities:
```typescript
getCapabilities(): PlatformCapabilities {
const platform = Capacitor.getPlatform();
const isElectron = platform === "electron";
return {
hasFileSystem: true,
hasCamera: true,
isMobile: !isElectron, // false for Electron, true for mobile
isIOS: platform === "ios",
hasFileDownload: isElectron, // Electron can download files directly
needsFileHandlingInstructions: !isElectron, // Mobile needs instructions
isNativeApp: true,
};
}
```
### Unified Database Layer
All platforms use the same SQLite database through Capacitor plugins:
- **Mobile**: `@capacitor-community/sqlite` plugin
- **Desktop**: Same plugin via Capacitor Electron
- **Web**: IndexedDB fallback with absurd-sql
### Feature Parity
The same Capacitor plugins work across all platforms:
- File system operations
- Camera access
- SQLite database
- Deep linking
- Sharing functionality

Write Preview
Loading…
Cancel
Save