128 lines
4.1 KiB
Markdown
128 lines
4.1 KiB
Markdown
# Eigen Desktop
|
|
|
|
An Electron wrapper for the web applications in this monorepo. Powered by **electron-vite** for development and **electron-builder** for production packaging.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# From the monorepo root
|
|
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Development (starts both the web dev server and Electron)
|
|
pnpm dev:desktop
|
|
|
|
# Build for production
|
|
pnpm build:desktop
|
|
|
|
# Package for distribution
|
|
pnpm package:desktop
|
|
```
|
|
|
|
---
|
|
|
|
## How It Works
|
|
|
|
| Environment | Behavior |
|
|
|---|---|
|
|
| **Development** | Electron loads the Vite dev server (`http://localhost:5173`). Hot reload works normally. |
|
|
| **Production** | Electron registers a custom `app://` protocol that serves the static build output of the target web app. SPA client-side routing is fully supported via an `index.html` fallback. |
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
apps/desktop/
|
|
├── docs/ # Documentation
|
|
│ ├── CONFIGURATION.md # Target app, routing, HashRouter fallback
|
|
│ ├── AUTO_UPDATER.md # Release process, CI/CD, code signing
|
|
│ └── IPC_ARCHITECTURE.md # Security model, adding new features
|
|
├── scripts/
|
|
│ └── copy-web-dist.ts # Prebuild: copies web app build → web-dist/
|
|
├── src/
|
|
│ ├── main/
|
|
│ │ └── index.ts # Main process: protocol, CORS, IPC, updater
|
|
│ ├── preload/
|
|
│ │ └── index.ts # Secure contextBridge API
|
|
│ └── renderer/
|
|
│ └── index.html # Renderer shell (CSP reference)
|
|
├── .env # Target app configuration
|
|
├── electron-builder.yml # Packaging & auto-update config
|
|
├── electron-vite.config.ts # Build config (main, preload, renderer)
|
|
├── package.json
|
|
├── tsconfig.json
|
|
├── tsconfig.main.json
|
|
├── tsconfig.preload.json
|
|
└── tsconfig.renderer.json
|
|
```
|
|
|
|
---
|
|
|
|
## Scripts
|
|
|
|
| Script | Description |
|
|
|---|---|
|
|
| `pnpm dev` | Start electron-vite dev server |
|
|
| `pnpm build` | Compile TypeScript → `out/` |
|
|
| `pnpm prebuild` | Copy target web app's `dist/` → `web-dist/` |
|
|
| `pnpm package` | Build + package for current platform |
|
|
| `pnpm package:win` | Package for Windows (NSIS) |
|
|
| `pnpm package:mac` | Package for macOS (DMG + ZIP) |
|
|
| `pnpm package:linux` | Package for Linux (AppImage) |
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
The target web app is configured via `.env`:
|
|
|
|
```env
|
|
DESKTOP_TARGET_APP=web
|
|
DESKTOP_DEV_SERVER_URL=http://localhost:5173
|
|
```
|
|
|
|
See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for details on switching target apps and routing fallbacks.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
### Custom `app://` Protocol
|
|
Serves the web app's static build with SPA routing support. Includes path traversal protection and CSP header injection.
|
|
|
|
### Hardware Printing
|
|
The React app can list printers and trigger print jobs via `window.electronAPI.getPrinters()` and `window.electronAPI.print()`.
|
|
|
|
### Auto-Update
|
|
Background update checks via GitHub Releases with download progress forwarding to the React UI. See [docs/AUTO_UPDATER.md](docs/AUTO_UPDATER.md).
|
|
|
|
### CORS Bypass
|
|
API requests from the `app://` origin are transparently handled by stripping non-standard Origin headers and injecting CORS response headers.
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
- `contextIsolation: true` — preload runs in an isolated context
|
|
- `nodeIntegration: false` — no Node.js APIs in the renderer
|
|
- `sandbox: true` — Chromium sandbox enabled
|
|
- `webSecurity: true` — same-origin policy enforced
|
|
- Path traversal protection in the custom protocol handler
|
|
- CSP headers injected on all HTML responses
|
|
|
|
See [docs/IPC_ARCHITECTURE.md](docs/IPC_ARCHITECTURE.md) for the full security model and how to safely extend the app.
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| Document | Contents |
|
|
|---|---|
|
|
| [CONFIGURATION.md](docs/CONFIGURATION.md) | Target app switching, `app://` protocol internals, HashRouter fallback procedure |
|
|
| [AUTO_UPDATER.md](docs/AUTO_UPDATER.md) | Release workflow, CI/CD variables, S3/generic provider switching, code signing |
|
|
| [IPC_ARCHITECTURE.md](docs/IPC_ARCHITECTURE.md) | Security model, Three-Step Bridge pattern, existing IPC channels, extension guide |
|