OmniRoute Tech Stack: Node.js, Next.js, and SQLite Implementation

OmniRoute is a Node.js 22+ application built on Next.js 16 with the App Router and uses SQLite via better-sqlite3 for local data persistence.

OmniRoute is an open-source AI request router developed by diegosouzapw. The repository combines a modern Node.js runtime with Next.js server capabilities and an embedded SQLite database to deliver a high-performance, self-hosted gateway supporting 357 LLM providers.

Node.js Runtime and Version Requirements

OmniRoute targets Node.js 22 and 24 as its primary execution environments. The package.json explicitly declares these engine constraints, ensuring compatibility across development and production deployments.

All npm scripts—including dev, build, and start—execute within this Node.js environment. To initialize the application locally:

# Install dependencies

npm install

# Start the development server on port 20128

npm run dev

Source: package.json scripts

Next.js 16 and App Router Architecture

The web framework layer runs on Next.js 16, utilizing the App Router paradigm for server-side API handling. RESTful endpoints are colocated with application logic under src/app/api/v1/..., following Next.js file-system routing conventions.

API Route Implementation

API endpoints are implemented as TypeScript modules exporting HTTP method handlers. The chat completion endpoint demonstrates this pattern:

// src/app/api/v1/chat/completions/route.ts
import { NextResponse } from 'next/server';
import { handleChatCore } from '@/open-sse/handlers/chatCore';

export async function POST(req: Request) {
  const body = await req.json();
  const result = await handleChatCore(body);
  return NextResponse.json(result);
}

Source: src/app/api/v1/chat/completions/route.ts

The Next.js configuration resides in next.config.mjs, which defines experimental features and build optimizations for the App Router.

SQLite Database Integration

Data persistence relies on SQLite via the better-sqlite3 driver, providing a serverless relational database that requires no external database server configuration.

Database Connection Singleton

Connection management uses a singleton pattern defined in src/lib/db/core.ts. The getDbInstance() function initializes the database on first access and returns the same connection instance for subsequent queries:

// src/lib/db/core.ts
import Database from 'better-sqlite3';
import { resolveDataDir } from '@/shared/utils/path';

let db: Database | null = null;

export function getDbInstance(): Database {
  if (!db) {
    const dbPath = resolveDataDir('omniroute.db');
    db = new Database(dbPath);
  }
  return db;
}

Source: src/lib/db/core.ts

Schema Migrations

Database schema evolution is handled through SQL migration files stored in src/lib/db/migrations/. These scripts execute automatically on application startup:

-- src/lib/db/migrations/2024-01-01-create-users.sql
CREATE TABLE IF NOT EXISTS users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT NOT NULL UNIQUE,
  created_at TEXT DEFAULT (datetime('now'))
);

Source: src/lib/db/migrations/

TypeScript and Development Tooling

The codebase enforces type safety through TypeScript 6, configured in tsconfig.json to target ES2022 with ESNext modules. This setup supports the ESM-only architecture while maintaining compatibility with Node.js 22+.

Code quality is managed via ESLint and Prettier, with configurations in eslint.config.mjs and prettier.config.mjs respectively. These tools ensure consistent formatting across the TypeScript and Node.js codebase.

Additional Runtime Support

While Node.js is the production standard, OmniRoute includes experimental support for alternative runtimes and specialized streaming requirements.

Bun Compatibility

A lightweight Bun compatibility path exists for the test:bun:db smoke test suite. However, the production runtime remains strictly Node.js-based, and primary optimizations target the V8 engine.

open-sse Streaming Engine

The streaming request pipeline lives in the open-sse/ workspace directory. This module contains handlers, executors, and translators that leverage Node.js streams to manage Server-Sent Events (SSE) for real-time LLM responses.

Summary

• Node.js 22+ is the required runtime, with engine constraints enforced in package.json.
• Next.js 16 with App Router handles API routing, with endpoints located in src/app/api/v1/.
• SQLite via better-sqlite3 provides embedded storage, accessed through the singleton in src/lib/db/core.ts.
• TypeScript 6 targeting ES2022 ensures type-safe development across the ESM codebase.
• ESLint and Prettier maintain code quality standards.
• Experimental Bun support exists for testing, while the open-sse workspace manages streaming logic.

Frequently Asked Questions

What version of Node.js does OmniRoute require?

OmniRoute requires Node.js 22 or higher, with explicit support for Node.js 24. The engine requirement is strictly enforced in package.json to prevent runtime incompatibility.

How does OmniRoute handle SQLite database connections?

OmniRoute implements a singleton pattern in src/lib/db/core.ts. The getDbInstance() function creates a single better-sqlite3 connection on first invocation and reuses it throughout the application lifecycle, preventing multiple file handles to the SQLite database.

Can OmniRoute run on Bun instead of Node.js?

OmniRoute includes optional Bun compatibility through the test:bun:db script for smoke testing, but the production runtime remains Node.js. All primary features are optimized and validated against Node.js 22+.

Where are the API routes defined in OmniRoute?

API routes follow the Next.js App Router file-system convention under src/app/api/v1/.... For example, the chat completions endpoint is implemented at src/app/api/v1/chat/completions/route.ts, exporting standard HTTP method handlers like POST.

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