new-api/electron/README.md

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.

Architecture

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

Development

Prerequisites

1. Build the Go backend first:

cd ..
go build -o new-api

2. Install Electron dependencies:

cd electron
npm install

Running in Development Mode

npm start

This will:

• Start the Go backend on port 3000
• Open an Electron window pointing to http://localhost:3000
• Enable DevTools for debugging

Building for Production

Quick Build (Current Platform)

Use the provided build script:

./build.sh

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:

cd ../web
DISABLE_ESLINT_PLUGIN='true' bun run build

2. Build backend:

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:

cd electron
npm install

# All platforms
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)

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:

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

Configuration

Port

The app uses port 3000 by default. To change:

Edit electron/main.js:

const PORT = 3000; // Change to your desired port

Data Directory

• Development: Uses data/ in the project root
• Production: Uses Electron's userData directory:
  • 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:

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:

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