# How to Build OmniRoute from Source: Complete Build Guide for v3.8.50

> Learn to build OmniRoute v3.8.50 from source. Follow our guide to install Node.js, fetch dependencies, and compile the release bundle for a custom server.

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

---

**Building OmniRoute from source requires Node.js ≥22, running `npm install` to fetch dependencies including the `open-sse` workspace, then executing `npm run build:release` to create a standalone server bundle in `dist/`.** Optional components include a native MITM proxy addon built with `npm run build:native:tproxy` and an Electron desktop client built from the `electron/` workspace.

OmniRoute is a TypeScript-heavy Next.js application that ships a standalone server bundle, an optional Electron desktop client, and a native MITM proxy addon. According to the diegosouzapw/OmniRoute source code, the full build process consists of three main phases: dependency installation, core server compilation, and optional auxiliary binary generation.

## Prerequisites

Before building OmniRoute from source, ensure your environment meets the following requirements:

- **Node.js ≥22.0.0** (the [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) specifies `"engines": { "node": ">=22.0.0 <23 || >=24.0.0 <27" }`)
- **Git** for cloning the repository
- **C build tools** (optional) if compiling the native MITM transparent proxy addon
- **npm** (comes with Node.js)

## Step-by-Step Build Guide

### 1. Clone the Repository

Checkout the specific release branch to ensure reproducible builds:

```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
git switch release/v3.8.50

```

### 2. Install Dependencies

Run the install command from the repository root. This pulls all Node.js and TypeScript dependencies, including the `open-sse` workspace, and triggers a post-install hook that compiles `better-sqlite3`:

```bash
npm install

```

If a C toolchain is present on your system, this step also prepares the native MITM addon for subsequent compilation.

### 3. Build the Core Server

OmniRoute uses **Turbopack** by default for faster builds, but you can force Webpack by setting `OMNIROUTE_USE_TURBOPACK=0` before running the build command.

**Standard development build:**

```bash
npm run build

```

This executes `next build`, creates intermediate files in `.build/next/`, and assembles a self-contained standalone bundle copied into `dist/`.

**Production release build (recommended for deployments):**

```bash
npm run build:release

```

This command cleans the `.build/` and `dist/` directories first, runs the full build pipeline via `scripts/build/assembleStandalone.mjs`, and writes a sentinel file `dist/BUILD_SHA` containing the short git commit hash (`git rev-parse --short HEAD`). This is the exact process documented in [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md) that CI expects to succeed.

### 4. Build the MITM Transparent Proxy Addon (Optional)

To compile the native N-API addon for transparent proxy interception:

```bash
npm run build:native:tproxy

```

This runs `node-gyp rebuild` in `src/mitm/tproxy/native/` to compile [`src/mitm/tproxy/native/transparent.c`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/native/transparent.c) into `transparent.node`. The resulting binary is automatically copied into the final standalone bundle. This step is non-fatal on platforms without a C toolchain—the server will run without proxy capabilities.

### 5. Build the Electron Desktop Client (Optional)

For the desktop application wrapper:

```bash
cd electron
npm install                    # Install Electron-specific dependencies

npm run build                  # Build the renderer (Next.js) part

npm run electron:build         # Package for host OS (AppImage, .dmg, .exe)

```

The Electron process reuses the Next.js bundle produced by the root `npm run build` and packages it using `electron-builder`. The entry point is [`electron/main.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/main.js), which loads the built Next.js bundle.

### 6. Verify the Build Output

After successful compilation, verify these artefacts exist:

- **Server bundle**: Located in `dist/` (created by `scripts/build/assembleStandalone.mjs`)
- **Build SHA**: `dist/BUILD_SHA` matches your current git commit
- **MITM addon**: `src/mitm/tproxy/native/transparent.node` (if built)
- **Electron package**: Output in `electron/dist/` (if built)

## Build Scripts Reference

| Script | Purpose | Output Location |
|--------|---------|-----------------|
| `npm run build` | Standard Next.js build with Turbopack | `.build/next/standalone` → `dist/` |
| `npm run build:release` | Clean build with SHA sentinel for releases | `dist/` with `dist/BUILD_SHA` |
| `npm run build:native:tproxy` | Compile MITM C addon | `src/mitm/tproxy/native/transparent.node` |
| `npm run build` (in `electron/`) | Electron renderer build | Reuses root `dist/` |

## CI/CD One-Liner

For automated pipelines, combine all steps into a single command chain:

```bash
git clone -b release/v3.8.50 https://github.com/diegosouzapw/OmniRoute.git && \
cd OmniRoute && \
npm ci && \
npm run build:release && \
npm run build:native:tproxy && \
(cd electron && npm ci && npm run electron:build)

```

You can configure build behavior using environment variables in a `.env` file:

```bash
OMNIROUTE_BASE_PATH=""          # Root URL path

OMNIROUTE_USE_TURBOPACK="1"     # Set to "0" for Webpack fallback

STORAGE_ENCRYPTION_KEY_VERSION="v1"

```

## Summary

- **Clone** the `release/v3.8.50` branch and ensure Node.js ≥22 is installed.
- **Install** dependencies with `npm install`, which automatically compiles `better-sqlite3`.
- **Build** the core server using `npm run build:release` to produce a standalone bundle in `dist/` with a SHA verification file.
- **Toggle** the bundler by setting `OMNIROUTE_USE_TURBOPACK=0` if you encounter memory constraints on low-RAM systems.
- **Compile** optional native addons with `npm run build:native:tproxy` and the desktop client from the `electron/` workspace.
- **Verify** the build outputs match the checks defined in [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md).

## Frequently Asked Questions

### What Node.js version is required to build OmniRoute?

OmniRoute requires **Node.js ≥22.0.0** or any version between ≥24.0.0 and <27, as specified in the `engines` field of [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json). Using an older version will cause dependency resolution or runtime errors.

### Can I build OmniRoute without the native MITM proxy addon?

Yes. The `npm run build:native:tproxy` step is entirely optional. If you skip it or lack a C toolchain, the build process will complete successfully, and the server will run normally—simply without transparent proxy interception capabilities.

### Where is the build output located after running npm run build?

The standalone server bundle is written to `dist/` (copied from `.build/next/standalone` by the assembly script). If you ran `npm run build:release`, you will also find a `dist/BUILD_SHA` file containing the short git commit hash for verification.

### How do I switch from Turbopack to Webpack during the build?

Set the environment variable `OMNIROUTE_USE_TURBOPACK=0` before running the build command. This is useful on Windows systems or low-RAM CI runners where Turbopack may cause memory pressure, as noted in the project documentation.