How to Update OmniRoute to the Latest Version: A Complete Upgrade Guide

Updating OmniRoute requires pulling the release/v3.8.50 branch, running npm ci to refresh Node.js dependencies, executing the migration runner at src/lib/db/migrationRunner.ts to update the SQLite schema, and restarting the Next.js or Electron service.

Staying current with the latest OmniRoute release ensures you receive critical security patches, new provider integrations, and schema improvements. The repository diegosouzapw/OmniRoute follows a strict release-branch workflow where the release/v3.8.50 branch represents the current stable line. This guide walks through the exact commands and file paths used to update your deployment safely.

Pull the Latest Release Branch

OmniRoute organizes stable releases through dedicated release branches. To update your installation, fetch the remote repository and checkout the current stable branch.

git fetch origin
git checkout release/v3.8.50
git pull origin release/v3.8.50

This operation updates your working directory with the latest source code, including changes to the API routes in src/app/api/v1/ and any provider catalog additions.

Refresh Node.js Dependencies and Environment

After pulling the latest code, synchronize your local Node.js environment with the exact dependency tree specified in package.json. OmniRoute targets Node.js 22 or 24 and uses ES modules, making engine compatibility critical.

Run the following command to install locked dependencies:

npm ci   # uses package-lock.json for reproducible installs

The npm ci command respects the engine field in package.json, ensuring your runtime matches the project's requirements.

Apply Database Migrations Safely

Every release may introduce schema changes to the SQLite database. OmniRoute handles these updates through a controlled migration system located in db/migrations/.

Execute the migration runner to apply pending SQL files inside transactions:

node --import tsx/esm src/lib/db/migrationRunner.ts

This script sequentially processes each versioned migration script (e.g., 001_initial_schema.sql) in db/migrations/, ensuring atomic updates that prevent data corruption.

Restart the Service and Verify

Once the codebase and database schema are synchronized, restart your application instance. The command depends on your deployment target.

For the Next.js API server:

npm run start

For the Electron desktop wrapper:

npm run electron:build

After restart, confirm that the src/app/api/v1/ routes respond correctly and that provider entries load without errors.

Validate the Update Using the Release Checklist

Before considering the upgrade complete, verify your deployment against the official Release Checklist documented in docs/ops/RELEASE_CHECKLIST.md. This file outlines the exact order of operations, required environment variables, and post-upgrade health checks used by maintainers for every release. Cross-referencing your update against this checklist ensures no configuration steps were missed.

Summary

• Checkout the stable branch: Use git checkout release/v3.8.50 to pull the latest stable code from diegosouzapw/OmniRoute.
• Lock dependencies: Run npm ci to install exact versions defined in package.json for Node.js 22/24 compatibility.
• Migrate the database: Execute node --import tsx/esm src/lib/db/migrationRunner.ts to apply SQLite schema changes from db/migrations/.
• Restart services: Use npm run start for the Next.js server or npm run electron:build for the desktop client.
• Verify against documentation: Consult docs/ops/RELEASE_CHECKLIST.md to confirm post-upgrade health.

Frequently Asked Questions

How do I check which version of OmniRoute is currently running?

Inspect your local git branch using git branch --show-current to confirm you are on release/v3.8.50, or check the repository's latest tag. The package.json file also contains version metadata that reflects the current release line.

What happens if I skip the database migration step?

Skipping src/lib/db/migrationRunner.ts leaves your SQLite schema out of sync with the application code. This mismatch can cause runtime errors in src/app/api/v1/ routes or data integrity failures when the application attempts to access tables that do not exist or have incorrect columns.

Can I update OmniRoute without downtime?

For production deployments, you can minimize downtime by performing the git pull and npm ci steps on a staging directory, then briefly stopping the service to run migrations and switch symlinks. However, the migration runner in src/lib/db/migrationRunner.ts requires a brief lock on the database file, so zero-downtime updates depend on your specific infrastructure setup.

Which Node.js version is required for OmniRoute v3.8.50?

The package.json specifies Node.js 22 or 24 as the supported runtime. Using older versions may result in ES module resolution errors or incompatible dependency behavior, particularly with the tsx/esm loader used during database migrations.

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