WIP: add Electron platform configuration to Capacitor

- Add electron platform section to capacitor.config.json - Configure deep linking with timesafari:// scheme - Set up build options for macOS, Windows, and Linux - Configure output directory and file inclusion - Add platform-specific build targets (DMG, NSIS, AppImage) - Support both x64 and arm64 architectures for macOS - Set appropriate app categories for each platform This enables building TimeSafari as a native desktop application using Capacitor's Electron platform while maintaining existing mobile and web functionality.
2025-06-25 12:50:46 +00:00
parent ca014a52de
commit ea0f49d5c3
29 changed files with 420 additions and 1987 deletions
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -9,7 +9,8 @@ For a quick dev environment setup, use [pkgx](https://pkgx.dev).
 - Node.js (LTS version recommended)
 - npm (comes with Node.js)
 - Git
- For desktop builds: Additional build tools based on your OS
+- For mobile builds: Android Studio (Android) or Xcode (iOS)
+- For desktop builds: Capacitor Electron platform

 ## Unified Build Scripts

@@ -28,8 +29,6 @@ TimeSafari now uses unified build scripts that automatically handle environment

 | Script | Purpose | Command |
 |--------|---------|---------|
-| `electron-dev.sh` | Electron development | `./scripts/electron-dev.sh` |
-| `electron-build.sh` | Electron build | `./scripts/build-electron.sh` |
 | `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` |
@@ -41,25 +40,22 @@ All scripts automatically set the correct environment variables for their build

 | Build Type | VITE_PLATFORM | VITE_PWA_ENABLED | VITE_DISABLE_PWA | NODE_ENV |
 |------------|---------------|------------------|------------------|----------|
-| `electron` | electron | false | true | production* |
 | `capacitor` | capacitor | false | true | - |
 | `web` | web | true | false | - |

-*NODE_ENV=production only set when production mode is enabled
-
 ### CLI Options

 All scripts support these options:

 ```bash
 # Show help
-./scripts/build-electron.sh --help
+./scripts/build-capacitor.sh --help

 # Enable verbose logging
-./scripts/build-electron.sh --verbose
+./scripts/build-capacitor.sh --verbose

 # Show environment variables
-./scripts/build-electron.sh --env
+./scripts/build-capacitor.sh --env
 ```

 ## Forks
@@ -102,12 +98,14 @@ npx jsr add @nostr/tools
 **Reason**: Resolved Vite/Rollup build issues with deep imports

 **Before** (npm):
+
 ```typescript
 import { finalizeEvent } from "nostr-tools/lib/cjs/index.js";
 import { accountFromExtendedKey } from "nostr-tools/lib/cjs/nip06.js";
 ```

 **After** (JSR):
+
 ```typescript
 import { finalizeEvent } from "@nostr/tools";
 import { accountFromExtendedKey } from "@nostr/tools/nip06";
@@ -210,102 +208,92 @@ VITE_DEFAULT_PUSH_SERVER=https://timesafari.app
 VITE_PASSKEYS_ENABLED=true
 ```

-## Desktop Build (Electron)
+## Desktop Build (Capacitor Electron)
+
+### Prerequisites
+
+1. Install Capacitor CLI:
+
+   ```bash
+   npm install -g @capacitor/cli
+   ```
+
+2. Add Electron platform:
+
+   ```bash
+   npx cap add electron
+   ```

 ### Development

 For development with automatic environment setup:

 ```bash
-./scripts/electron-dev.sh
+# 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 with automatic environment setup:
+For production builds:

 ```bash
-./scripts/build-electron.sh
+# Build web assets
+npm run build:capacitor
+
+# Sync with Capacitor
+npx cap sync electron
+
+# Build Electron app
+npx cap build electron
 ```

-### Linux Packaging
+### Packaging

-```bash
-# Build AppImage (recommended)
-./scripts/build-electron-linux.sh
+Capacitor Electron uses electron-builder for packaging. Configure the build in `capacitor.config.json`:

-# Build .deb package
-./scripts/build-electron-linux.sh deb
-
-# Build production AppImage
-./scripts/build-electron-linux.sh prod
+```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"]
+        }
+      }
+    }
+  }
+}
 ```

-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 Packaging
-
-```bash
-# Build standard Mac package
-./scripts/build-electron-mac.sh
-
-# Build universal package (Intel + Apple Silicon)
-./scripts/build-electron-mac.sh universal
-```
-
-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 in `.env` file:
-   ```bash
-   CSC_LINK=/path/to/your/certificate.p12
-   CSC_KEY_PASSWORD=your_certificate_password
-   APPLE_ID=your_apple_id
-   APPLE_ID_PASSWORD=your_app_specific_password
-   ```
-
-2. Build with signing:
-   ```bash
-   ./scripts/build-electron-mac.sh
-   ```
-
 ### Running the Packaged App

- **Linux**:
-  - 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
-    ```
-
- **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
+- **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)

@@ -601,12 +589,12 @@ For iOS deep links, configure the URL scheme in Xcode:
 ### Common Issues

 1. **Environment Variables Not Set**
-   - Use `--env` flag to check current environment: `./scripts/build-electron.sh --env`
+   - 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-electron.sh --verbose`
+   - Use `--verbose` flag for detailed logging: `./scripts/build-capacitor.sh --verbose`
   - Check prerequisites are installed
   - Verify all dependencies are installed: `npm install`

@@ -615,14 +603,13 @@ For iOS deep links, configure the URL scheme in Xcode:
   - Check file permissions on build directories

 4. **Platform-Specific Issues**
-   - **Linux**: Ensure AppImage dependencies are installed
-   - **macOS**: Check code signing certificates and entitlements
   - **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-electron.sh --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`
@@ -633,20 +620,47 @@ For iOS deep links, configure the URL scheme in Xcode:
 |----------|------|-------------|-----------------|-------|
 | `web` | web | true | false | Standard web browser |
 | `capacitor` | capacitor | false | true | Mobile app (iOS/Android) |
-| `electron` | electron | false | true | Desktop app (Windows/macOS/Linux) |
+| `electron` | capacitor | false | true | Desktop app (via Capacitor Electron) |

-## Electron Build: CSS Injection
+## Platform Service Architecture

-The Electron build now uses Vite's built-in CSS handling with a custom plugin (`electron-css-injection`) that automatically injects CSS links into the generated `index.html` file. This replaces the previous manual CSS injection script.
+TimeSafari uses a unified platform service architecture that works across all platforms:

-**Plugin:** `vite.config.electron.mts` - `electron-css-injection` plugin
+### Platform Detection

-**Features:**
- Automatically detects and injects CSS files generated by Vite
- Ensures proper relative paths for Electron builds
- Handles multiple CSS files if present
- Provides detailed logging during build process
+The `CapacitorPlatformService` automatically detects the platform and adjusts capabilities:

-**No manual intervention required** - CSS injection is handled automatically during the Vite build process.
+```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,
+  };
+}
+```

-**Author:** Matthew Raymer
+### 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