# How to Build and Run the OmniRoute Electron Desktop App on Windows, macOS, and Linux

> Build and run the OmniRoute Electron desktop app on Windows, macOS, and Linux. Follow simple commands to install dependencies and generate native installers.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-05

---

**To build and run the OmniRoute Electron desktop app, install Node ≥ 22 and pnpm, run `pnpm install`, then execute `npm run electron:build:win`, `npm run electron:build:mac`, or `npm run electron:build:linux` to generate native installers for Windows, macOS, or Linux respectively.**

The OmniRoute repository by diegosouzapw ships a cross-platform desktop wrapper built with **Electron** and packaged using **electron-builder**. The source code lives in the `electron/` directory and supports creating native installers for all three major operating systems. This guide covers the complete workflow from dependency installation to running both development and production builds.

## Prerequisites

Before building the OmniRoute Electron desktop app, ensure your environment meets these requirements:

- **Node.js ≥ 22** – The repository targets recent Node versions for modern ES features.
- **pnpm** – The monorepo uses pnpm workspaces. Install globally with `npm i -g pnpm` if missing.
- **Platform build tools** – Linux requires `make`, `gcc`, and standard C toolchains; macOS needs Xcode Command Line Tools; Windows requires Visual C++ Build Tools.

## Install Workspace Dependencies

From the repository root, install all workspace packages including the Electron application:

```bash
pnpm install

```

This command installs dependencies across the monorepo and triggers post-install scripts that patch native modules like `better-sqlite3` for the Electron runtime.

## Building for Specific Operating Systems

The build process uses npm scripts defined in the root [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) and [`electron/package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/package.json). Each platform target runs `electron-builder` with specific flags.

### Windows

Run the Windows-specific build script to generate `.exe` or `.msi` installers:

```bash
npm run electron:build:win

```

This script expands to `npm run build && cd electron && npm run build:win`, which first compiles the Next.js backend, then invokes `electron-builder --win`. Output appears in `electron/dist-electron/` as a Windows installer.

### macOS

Build universal binaries or architecture-specific packages:

```bash

# Universal binary (Intel + Apple Silicon)

npm run electron:build:mac

# Apple Silicon only

npm run electron:build:mac-arm64

# Intel only

npm run electron:build:mac-x64

```

Each script executes `electron-builder` with `--mac` flags and corresponding architecture targets. The resulting signed `.dmg` or `.pkg` files land in `electron/dist-electron/`.

### Linux

Generate AppImage, Debian, and RPM packages:

```bash
npm run electron:build:linux

```

This runs `electron-builder --linux`, producing `.AppImage`, `.deb`, and `.rpm` artifacts under `electron/dist-electron/`.

**Critical detail:** The `extraResources` configuration in [`electron/package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/package.json) bundles standalone runtime dependencies into `resources/app/node_modules`, ensuring the packaged app runs without a separate Node installation.

## Development Mode vs Packaged Builds

### Development Mode (Any OS)

Use the development script to run the app with hot-module reloading:

```bash
npm run electron:dev

```

This starts the Next.js dev server (`npm run dev`) and launches Electron with `--no-sandbox` (required for the bundled server). UI changes reflect immediately without rebuilding.

### Running Packaged Builds

After building, launch the native binary directly:

```bash

# Windows

open electron/dist-electron/OmniRoute-*.exe

# macOS

open electron/dist-electron/OmniRoute-*.dmg

# Linux

./OmniRoute-*.AppImage

```

The app initializes a local backend on a random high port, stores its SQLite database in a platform-specific data directory (managed by [`src/shared/hooks/useElectron.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/hooks/useElectron.ts)), and presents the main UI.

## Smoke Testing Packaged Apps

Verify your build with the CI-friendly smoke harness:

```bash
npm run electron:smoke:packaged

```

This script builds the installer, extracts it, and runs the binary with a temporary data directory (`ELECTRON_SMOKE_DATA_DIR`). It validates that the server starts correctly, the UI communicates with the backend, and auto-update logic functions properly.

## Troubleshooting Common Issues

| Symptom | Cause | Solution |
|---------|-------|----------|
| **Cannot find native module** (`better-sqlite3`) | `extraResources` copy failed | Verify [`electron/package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/package.json) contains the `extraResources` entry copying `../.build/electron-standalone/node_modules` |
| **App crashes on first launch after upgrade** | DB migrations exceed readiness probe timeout | The startup code probes the health endpoint with `ELECTRON_SMOKE_TIMEOUT_MS` for generous margins |
| **Missing updates on macOS** | V8 version mismatch with `better-sqlite3` | The project pins Electron to `41.x` for V8 compatibility |
| **Sandbox errors on Linux** | Missing `--no-sandbox` flag | Use `npm run electron:dev` (includes `--no-sandbox`) or enable the sandbox explicitly in packaged binaries |

## Key Source Files

Understanding these files helps debug build issues:

- **[`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js)** – Main process entry point that launches the server, handles updates, and manages the IPC bridge.
- **[`electron/preload.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/preload.js)** – Exposes a safe API (`window.electronAPI`) to the renderer process.
- **[`electron/package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/package.json)** – Contains npm scripts, electron-builder configuration, and runtime dependencies.
- **[`src/shared/hooks/useElectron.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/hooks/useElectron.ts)** – React hook that detects the Electron environment and forwards IPC calls.
- **[`electron/types.d.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/types.d.ts)** – Type definitions for the IPC API consumed by the UI.
- **`scripts/dev/smoke-electron-packaged.mjs`** – Automated smoke-test harness for packaged binaries.

## Summary

- **Install** Node ≥ 22 and pnpm, then run `pnpm install` from the repository root.
- **Build** platform-specific installers using `npm run electron:build:win`, `:mac`, or `:linux`.
- **Develop** using `npm run electron:dev` for hot-reload functionality.
- **Test** packaged builds with `npm run electron:smoke:packaged` to verify server startup and API connectivity.
- **Debug** native module issues by checking `extraResources` configuration in [`electron/package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/package.json).

## Frequently Asked Questions

### What Node version does OmniRoute Electron require?

The build system requires **Node.js ≥ 22** according to the repository configuration. Earlier versions may fail during the native module compilation step.

### Why does the Linux build need `--no-sandbox`?

The bundled Next.js server requires disabling Chromium's sandbox in development mode. The `npm run electron:dev` script automatically includes this flag, but packaged Linux binaries may need explicit sandbox configuration depending on your distribution's security policies.

### Where are the built installers located?

Platform-specific installers appear in `electron/dist-electron/` following a successful build. Windows produces `.exe` files, macOS generates `.dmg` packages, and Linux creates `.AppImage`, `.deb`, and `.rpm` artifacts.

### How does the app handle database storage?

The Electron main process stores the SQLite database in a platform-specific data directory. The path resolution logic lives in [`src/shared/hooks/useElectron.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/hooks/useElectron.ts), which abstracts OS-specific storage locations for consistent data persistence across Windows, macOS, and Linux.