# OmniRoute Node.js Version Requirements: Complete Compatibility Guide

> Find OmniRoute Node.js version requirements. Supports Node.js 22.22.2+ (LTS) and 24-26.x. Excludes 23.x for server, Electron, and Opencode packages.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: api-reference
- Published: 2026-09-01

---

**OmniRoute requires Node.js 22.22.2 or higher (LTS), explicitly excludes version 23.x, and supports Node.js 24 through 26.x across its core server, Electron client, and Opencode packages.**

OmniRoute is a multi-package routing platform with strict Node.js runtime requirements defined in each component's [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json). Understanding these Node.js version requirements ensures your development environment and deployment pipelines remain compatible with the framework's engine constraints.

## Core Server and CLI Node.js Requirements

The **OmniRoute core server and CLI tools** enforce a precise Node.js version range in the root [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json):

```json
// package.json
{
  "engines": {
    "node": ">=22.22.2 <23 || >=24.0.0 <27"
  }
}

```

This specification, found at [`release/v3.8.51/package.json#L63`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/package.json#L63), establishes:

- **Minimum supported**: Node.js 22.22.2 (LTS)
- **Explicitly excluded**: Node.js 23.x series
- **Secondary range**: Node.js 24.0.0 through 26.x

The exclusion of Node.js 23.x reflects this version's non-LTS status, reducing maintenance burden and runtime instability risks.

## Electron Desktop Client Requirements

The **Electron desktop client** mirrors the core server's Node.js version requirements exactly. In [`electron/package.json#L13`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/electron/package.json#L13), the same `engines.node` field appears:

```json
// electron/package.json
{
  "engines": {
    "node": ">=22.22.2 <23 || >=24.0.0 <27"
  }
}

```

This alignment ensures consistent behavior between the server-side logic and the packaged desktop application, eliminating Electron-specific runtime incompatibilities.

## Opencode Provider and Plugin Requirements

The **Opencode provider** and **plugin packages** introduce slightly stricter minimums while maintaining the same upper bounds:

| Package | File Path | Node.js Requirement |
|---------|-----------|---------------------|
| Opencode provider | [`@omniroute/opencode-provider/package.json#L49`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/@omniroute/opencode-provider/package.json#L49) | `>=22.22.3` |
| Opencode plugin | [`@omniroute/opencode-plugin/package.json#L52`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/@omniroute/opencode-plugin/package.json#L52) | `>=22.22.3` |

Both packages omit the explicit upper bound but inherit the repository's tested compatibility ceiling through peer dependency resolution and CI validation.

## Programmatic Version Verification

Enforce Node.js version requirements in your CI pipelines or startup scripts using this pattern:

```javascript
// utils/checkNodeVersion.js
const { engines } = require('../package.json');
const required = engines.node;                // ">=22.22.2 <23 || >=24.0.0 <27"
const semver = require('semver');

if (!semver.satisfies(process.version, required)) {
  console.error(
    `Node.js version ${process.version} is not supported. ` +
    `Required: ${required}`
  );
  process.exit(1);
}

```

Integrate this check into GitHub Actions workflows:

```yaml

# .github/workflows/ci.yml (excerpt)

steps:
  - name: Verify Node version
    run: node utils/checkNodeVersion.js

```

This approach replicates npm's native `engines` enforcement while providing explicit failure messages for debugging.

## Why OmniRoute Excludes Node.js 23.x

Node.js follows an alternating LTS release cadence where:

- **Even-numbered versions** (20, 22, 24, 26) receive long-term support
- **Odd-numbered versions** (21, 23, 25) serve as short-lived testing grounds

By excluding Node.js 23.x from its supported matrix, OmniRoute eliminates:

- Security patches that expire six months post-release
- API instability requiring frequent compatibility shims
- Dependency conflicts with native modules lacking 23.x binaries

This policy aligns with Node.js's own [release working group recommendations](https://github.com/nodejs/release#aligning-the-branches) for production deployments.

## Version Requirement Summary by Component

| Component | Minimum Version | Maximum Version | Source File |
|-----------|---------------|-----------------|-------------|
| Core server & CLI | 22.22.2 | 22.x or 24.x–26.x | [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) |
| Electron client | 22.22.2 | 22.x or 24.x–26.x | [`electron/package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/package.json) |
| Opencode provider | 22.22.3 | None specified | `@omniroute/opencode-provider/package.json` |
| Opencode plugin | 22.22.3 | None specified | `@omniroute/opencode-plugin/package.json` |

All components fundamentally target the **Node.js 22 LTS** and **Node.js 24–26 LTS** series as their validated runtime environment.

## Summary

- **Primary requirement**: Node.js 22.22.2 LTS or Node.js 24.0.0 through 26.x
- **Excluded version**: Node.js 23.x is explicitly unsupported across all OmniRoute packages
- **Stricter subpackages**: Opencode provider and plugin require minimum 22.22.3
- **Verification method**: Use `semver.satisfies()` against `engines.node` in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json)
- **Source of truth**: Root [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json), [`electron/package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/package.json), and scoped package manifests in `@omniroute/*`

## Frequently Asked Questions

### What happens if I run OmniRoute on Node.js 23.x?

Your package manager will emit an **EBADENGINE warning** during installation, and runtime behavior becomes undefined. Native dependencies may fail to compile, and OmniRoute's internal APIs may reference V8 features unstable in the 23.x series. Deployments on 23.x are explicitly unsupported.

### Can I use Node.js 22.22.0 or 22.22.1 instead of 22.22.2?

No. The patch-level minimums (22.22.2 for core, 22.22.3 for Opencode packages) reflect specific security fixes and backported features that OmniRoute's dependency tree requires. Earlier 22.x patches will fail `engines` validation.

### Does OmniRoute support Node.js 18 or 20 LTS?

No. The `>=22.22.2` lower bound eliminates these older LTS lines. OmniRoute likely uses Node.js 22-specific features such as the improved `fetch` implementation, `WebSocket` client, or `import.meta.dirname` that remain unavailable in Node.js 20.

### How do I pin Node.js version in Docker for OmniRoute?

Use an explicit LTS tag in your Dockerfile that satisfies the `engines` range:

```dockerfile
FROM node:22.22.2-alpine

# or

FROM node:24.0.0-alpine

```

Avoid `node:latest` or `node:current` tags, as these may resolve to Node.js 23.x during that release's availability window.