diff --git a/electron/README.md b/electron/README.md index 5122a1ba1..88463b8ae 100644 --- a/electron/README.md +++ b/electron/README.md @@ -1,172 +1,73 @@ # New API Electron Desktop App -This directory contains the Electron wrapper for New API, allowing it to run as a native desktop application on Windows, macOS, and Linux. +This directory contains the Electron wrapper for New API, providing a native desktop application with system tray support for Windows, macOS, and Linux. -## Architecture +## Prerequisites -The Electron app consists of: -- **main.js**: Main process that spawns the Go backend server and creates the application window -- **preload.js**: Preload script for secure context isolation -- **package.json**: Electron dependencies and build configuration +### 1. Go Binary (Required) +The Electron app requires the compiled Go binary to function. You have two options: -## Development - -### Prerequisites - -1. Build the Go backend first: +**Option A: Use existing binary (without Go installed)** ```bash -cd .. -go build -o new-api +# If you have a pre-built binary (e.g., new-api-macos) +cp ../new-api-macos ../new-api ``` -2. Install Electron dependencies: +**Option B: Build from source (requires Go)** +TODO + +### 3. Electron Dependencies ```bash cd electron npm install ``` -### Running in Development Mode +## Development +Run the app in development mode: ```bash npm start ``` This will: - Start the Go backend on port 3000 -- Open an Electron window pointing to `http://localhost:3000` -- Enable DevTools for debugging +- Open an Electron window with DevTools enabled +- Create a system tray icon (menu bar on macOS) +- Store database in `../data/new-api.db` ## Building for Production -### Quick Build (Current Platform) - -Use the provided build script: +### Quick Build ```bash -./build.sh -``` +# Ensure Go binary exists in parent directory +ls ../new-api # Should exist -This will: -1. Build the frontend (web/dist) -2. Build the Go binary for your platform -3. Package the Electron app - -### Manual Build Steps - -1. Build frontend: -```bash -cd ../web -DISABLE_ESLINT_PLUGIN='true' bun run build -``` - -2. Build backend: -```bash -cd .. -# macOS/Linux -go build -ldflags="-s -w" -o new-api - -# Windows -go build -ldflags="-s -w" -o new-api.exe -``` - -3. Build Electron app: -```bash -cd electron -npm install - -# All platforms +# Build for current platform npm run build -# Or specific platforms -npm run build:mac # macOS (DMG, ZIP) -npm run build:win # Windows (NSIS installer, Portable) -npm run build:linux # Linux (AppImage, DEB) +# Platform-specific builds +npm run build:mac # Creates .dmg and .zip +npm run build:win # Creates .exe installer +npm run build:linux # Creates .AppImage and .deb ``` -### Output - -Built apps are located in `electron/dist/`: -- **macOS**: `.dmg` and `.zip` -- **Windows**: `.exe` installer and portable `.exe` -- **Linux**: `.AppImage` and `.deb` - -## Cross-Platform Building - -To build for other platforms: - -```bash -# From macOS, build Windows app -npm run build:win - -# From macOS, build Linux app -npm run build:linux -``` - -Note: Building macOS apps requires macOS. Building Windows apps with code signing requires Windows. +### Build Output +- Built applications are in `electron/dist/` +- macOS: `.dmg` (installer) and `.zip` (portable) +- Windows: `.exe` (installer) and portable exe +- Linux: `.AppImage` and `.deb` ## Configuration ### Port - -The app uses port 3000 by default. To change: - -Edit `electron/main.js`: +Default port is 3000. To change, edit `main.js`: ```javascript -const PORT = 3000; // Change to your desired port +const PORT = 3000; // Change to desired port ``` -### Data Directory - -- **Development**: Uses `data/` in the project root -- **Production**: Uses Electron's `userData` directory: +### Database Location +- **Development**: `../data/new-api.db` (project directory) +- **Production**: - macOS: `~/Library/Application Support/New API/data/` - Windows: `%APPDATA%/New API/data/` - Linux: `~/.config/New API/data/` - -### Window Size - -Edit `electron/main.js` in the `createWindow()` function: -```javascript -mainWindow = new BrowserWindow({ - width: 1400, // Change width - height: 900, // Change height - // ... -}); -``` - -## Troubleshooting - -### Server fails to start - -Check the console logs in DevTools (Cmd/Ctrl+Shift+I). Common issues: -- Go binary not found (ensure it's built) -- Port 3000 already in use -- Database file permission issues - -### Binary not found in production - -Ensure the Go binary is built before running `electron-builder`: -```bash -go build -o new-api # macOS/Linux -go build -o new-api.exe # Windows -``` - -The binary must be in the project root, not inside `electron/`. - -### Database issues - -If you encounter database errors, delete the data directory and restart: -- Dev: `rm -rf data/` -- Prod: Clear Electron's userData folder (see "Data Directory" above) - -## Icon - -To add a custom icon: -1. Place a 512x512 PNG icon at `electron/icon.png` -2. Rebuild the app with `npm run build` - -## Security - -- Context isolation is enabled -- Node integration is disabled in renderer process -- Only safe APIs are exposed via preload script -- Backend runs as a local subprocess with no external network access by default \ No newline at end of file