Build Process for OmniRoute: Complete Guide to Production Deployment

The OmniRoute build process consists of dependency installation, Next.js compilation via scripts/build/build-next-isolated.mjs, and optional native binary generation, ultimately assembling a standalone production bundle in the dist/ directory.

OmniRoute is a full-stack routing application built on Next.js with optional native addons and Electron packaging support. Understanding the build process for OmniRoute is essential for deploying the core server, native MITM proxy components, or the desktop application. The entire workflow is orchestrated through npm scripts in the repository root and specialized build scripts located under scripts/build/.

Prerequisites and Environment Setup

Before compilation, the build environment requires proper configuration and dependency resolution.

Dependency Installation

Start by installing all Node.js and TypeScript packages using npm ci (preferred for CI/CD) or npm install. This fetches the required dependencies, including build tools like node-gyp for native addon compilation.

npm ci

Environment Configuration

The scripts/build/bootstrap-env.mjs script initializes critical environment variables that control the build behavior. As referenced in docs/reference/ENVIRONMENT.md, this script sets values such as OMNIROUTE_BUILD_PROFILE and OMNIROUTE_USE_TURBOPACK, which determine whether the build uses Turbopack or falls back to Webpack.

node scripts/build/bootstrap-env.mjs

Core Build Pipeline

The standard production build follows a two-stage process: compiling the Next.js application and assembling the distributable artifacts.

Next.js Production Compilation

The npm run build command invokes scripts/build/build-next-isolated.mjs, which executes a clean Next.js production build using next build. Depending on the OMNIROUTE_USE_TURBOPACK configuration, this process utilizes either Turbopack or Webpack for bundling. Intermediate output is deposited into .build/next/ for further processing.

npm run build

Standalone Bundle Assembly

After the Next.js compilation completes, scripts/build/assembleStandalone.mjs gathers the compiled server code, static assets, and any optional native modules into a single distributable directory. According to docs/ops/RELEASE_CHECKLIST.md, this step produces the final dist/ directory containing the complete, self-contained application ready for deployment.

npm run assemble

Optional Build Targets

OmniRoute supports additional build processes for advanced features and desktop distribution.

Native MITM Proxy Addon

Certain features, specifically the transparent proxy MITM functionality, require a compiled N-API binary. Running npm run build:native:tproxy triggers scripts/build/build-tproxy-native.mjs, which executes node-gyp rebuild inside src/mitm/tproxy/native to produce transparent.node. As documented in docs/security/MITM-TPROXY-DECRYPT.md, the resulting binary is automatically copied into the standalone bundle by assembleStandalone.mjs.

npm run build:native:tproxy

Electron Desktop Application

The Electron UI is built separately from the core server. As specified in electron/README.md, navigate to the electron/ directory and install dependencies before building platform-specific targets.

cd electron
npm ci
npm run build:linux   # or :win / :mac

Complete Build Reference

For a fresh deployment from source, execute the following sequence:

# Clone and enter repository

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute

# Install dependencies and build core application

npm ci
npm run build        # Compiles Next.js via build-next-isolated.mjs

npm run assemble     # Creates dist/ bundle

# Optional: Build native transparent proxy (Linux only)

npm run build:native:tproxy

# Optional: Build Electron desktop app

cd electron && npm ci && npm run build:linux

Summary

• Environment Setup: The scripts/build/bootstrap-env.mjs script configures build variables like OMNIROUTE_BUILD_PROFILE before compilation begins.
• Core Compilation: npm run build executes scripts/build/build-next-isolated.mjs, producing Next.js output in .build/next/ using Turbopack or Webpack.
• Artifact Assembly: scripts/build/assembleStandalone.mjs packages the application into the dist/ directory for production deployment.
• Native Addons: The transparent proxy requires npm run build:native:tproxy, which compiles transparent.node via node-gyp in src/mitm/tproxy/native.
• Desktop Builds: Electron packaging occurs independently within the electron/ directory using platform-specific npm scripts.

Frequently Asked Questions

What is the entry point for OmniRoute's build system?

The primary entry point is the npm run build command in the repository root, which invokes scripts/build/build-next-isolated.mjs. This script manages the Next.js compilation process and is referenced in the release checklist at docs/ops/RELEASE_CHECKLIST.md as the standard starting point for production builds.

How does OmniRoute handle environment variables during builds?

Environment configuration is managed by scripts/build/bootstrap-env.mjs, which sets variables such as OMNIROUTE_BUILD_PROFILE and OMNIROUTE_USE_TURBOPACK. These variables control whether the build uses Turbopack for faster compilation or falls back to standard Webpack bundling.

What build tools does OmniRoute use for the web application?

The web application uses Next.js as the primary framework, with scripts/build/build-next-isolated.mjs executing the next build command. The build can utilize either Turbopack (for faster builds) or Webpack (as a fallback) depending on the OMNIROUTE_USE_TURBOPACK environment variable setting.

When do I need to build the native transparent proxy addon?

You only need to build the native addon if you intend to use the MITM transparent proxy feature on Linux systems. This requires running npm run build:native:tproxy, which triggers scripts/build/build-tproxy-native.mjs to compile the transparent.node binary using node-gyp rebuild in the src/mitm/tproxy/native directory.

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