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

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:

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 and 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:

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:

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

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 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:

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:

# 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), and presents the main UI.

Smoke Testing Packaged Apps

Verify your build with the CI-friendly smoke harness:

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 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 – Main process entry point that launches the server, handles updates, and manages the IPC bridge.
• electron/preload.js – Exposes a safe API (window.electronAPI) to the renderer process.
• electron/package.json – Contains npm scripts, electron-builder configuration, and runtime dependencies.
• src/shared/hooks/useElectron.ts – React hook that detects the Electron environment and forwards IPC calls.
• 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.

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, which abstracts OS-specific storage locations for consistent data persistence across Windows, macOS, and Linux.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}