How to Update OmniRoute to the Latest Version: A Step-by-Step Guide

To update OmniRoute to the latest version, pull the current release branch, reinstall Node dependencies with npm ci, run database migrations via src/lib/db/migrationRunner.ts, and restart the service.

Upgrading OmniRoute ensures you receive the newest provider integrations, bug fixes, and security patches. The project maintains a release-branch workflow centered on the release/v3.8.50 branch as its current stable line. This guide walks through the exact commands and files involved in the update process according to the diegosouzapw/OmniRoute source code.

Update OmniRoute in Four Steps

Step 1: Pull the Latest Release Branch

Fetch the remote repository and switch to the newest stable branch. This brings in updated source code, new provider entries, and any critical fixes.

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

If you track tags instead of branches, checkout the specific release/vX.Y.Z tag that marks the latest stable release.

Step 2: Refresh Node Dependencies

OmniRoute targets Node 22 or 24 and uses ES modules. Run npm ci to install exact versions from package-lock.json, ensuring reproducible builds.

npm ci

The package.json in the repository root defines the engine requirements and dependency tree. Respecting these constraints prevents runtime module errors.

Step 3: Apply Database Migrations

Each release may add or modify SQLite tables. Execute the migration runner to apply pending schema changes safely within transactions.

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

This script reads SQL files from db/migrations/ (for example, 001_initial_schema.sql) and updates the local database schema. All migrations run inside transactions to prevent partial state.

Step 4: Restart the Service

Once code and database are synchronized, restart your deployment:

npm run start          # for the Next.js API server

# or

npm run electron:build # for the Electron desktop wrapper

Key Files Involved in OmniRoute Updates

File	Purpose
package.json	Declares Node version, scripts, and exact dependency versions
src/lib/db/migrationRunner.ts	Entry point that sequentially applies SQL migration files
db/migrations/	Directory containing versioned migration scripts
docs/ops/RELEASE_CHECKLIST.md	Official step-by-step guide used by maintainers
src/app/api/v1/	Core Next.js API routes affected by provider or schema changes

Verify Your Update

After restarting, confirm the deployment health through these checks:

• API endpoints under src/app/api/v1/ respond correctly
• Database version matches the latest migration timestamp
• Provider integrations listed in the newest release load without errors

The Release Checklist at docs/ops/RELEASE_CHECKLIST.md documents the exact order of operations, required environment variables, and post-upgrade validation steps used by the maintainers for every release.

Summary

• Pull the release/v3.8.50 branch (or latest tag) to receive source updates
• Run npm ci to install locked dependencies for Node 22/24
• Execute migrations with node --import tsx/esm src/lib/db/migrationRunner.ts
• Restart via npm run start or npm run electron:build
• Validate against the Release Checklist to confirm successful upgrade

Frequently Asked Questions

How do I know which release branch is current?

Check the default branch on GitHub or the latest tag matching release/vX.Y.Z. The release/v3.8.50 branch is the current stable line as documented in the repository.

What happens if I skip database migrations?

Skipping migrations leaves your SQLite schema out of sync with the codebase, causing runtime errors when new code references missing tables or columns. Always run src/lib/db/migrationRunner.ts after pulling updates.

Can I use npm install instead of npm ci?

npm ci is strongly preferred because it strictly follows package-lock.json for reproducible installs. npm install may update dependency versions beyond what the release tested, introducing compatibility risks.

How do I update the Electron desktop version specifically?

Pull the latest branch, run npm ci, apply migrations, then execute npm run electron:build rather than npm run start. The build process packages the updated Next.js API and frontend into the desktop wrapper.

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