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

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

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:

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:

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

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 that CI expects to succeed.

4. Build the MITM Transparent Proxy Addon (Optional)

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

npm run build:native:tproxy

This runs node-gyp rebuild in src/mitm/tproxy/native/ to compile 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:

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

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:

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.

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

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