Complete Guide to Build Scripts in OmniRoute: Development, Production, and Testing Commands

OmniRoute provides 20+ npm scripts centralized in package.json that cover Next.js development servers, production builds, TypeScript compilation, Electron desktop packaging, and comprehensive testing suites.

The OmniRoute repository (diegosouzapw/OmniRoute) manages all build automation through the root package.json file. These scripts provide a single source of truth for workflows ranging from local development to CI/CD pipelines, handling the web application, CLI tools, and Electron desktop builds.

Development Server and Production Builds

The core build scripts in OmniRoute handle both the Next.js web application and the standalone CLI distribution.

• npm run dev – Starts the Next.js development server with hot-reloading enabled. This corresponds to line 30 in package.json.

• npm run build – Executes next build to generate a production-ready bundle optimized for deployment.

• npm run build:release – Performs a clean rebuild, writes the current git SHA to dist/BUILD_SHA, and prepares the bundle for official releases. This script ensures reproducible builds with version tracking.

• npm start – Runs the compiled production server using next start, serving the optimized build output.

• npm run build:cli – Compiles the OmniRoute CLI package from TypeScript to JavaScript and places the binary in dist/cli. This uses the TypeScript configuration at scripts/cli/tsconfig.json for the build process.

# Start local development

npm run dev

# Create production build

npm run build

# Build the CLI tool separately

npm run build:cli

Code Quality and Type Checking Scripts

OmniRoute enforces strict code quality through dedicated linting and type-checking commands.

• npm run lint – Runs ESLint across the entire codebase to catch style violations and potential errors.

• npm run typecheck:core – Executes strict TypeScript checking for core modules with noImplicitAny disabled for faster feedback during development.

• npm run typecheck:noimplicit:core – Performs the same type checking but enforces no implicit any across all files, ensuring maximum type safety before releases.

• npm run check – A convenience shortcut that runs npm run lint && npm run test:all, providing a single quality gate to execute before commits.

• npm run check:cycles – Detects circular dependencies in the project that could cause runtime issues or bundling problems.

Electron Desktop Application Builds

OmniRoute supports desktop deployment through Electron, with specialized scripts for development and distribution.

• npm run electron:dev – Launches the Electron desktop app in development mode with watch-mode enabled, allowing rapid iteration on desktop-specific features.

• npm run electron:build – Builds the Electron binary for the host operating system, embedding the web assets into a standalone desktop application. This script utilizes scripts/electron/build.mjs to handle the packaging pipeline.

# Test desktop app during development

npm run electron:dev

# Package for distribution

npm run electron:build

Testing Suite Scripts

The testing infrastructure covers unit tests, integration tests, E2E browser tests, and ecosystem compatibility checks.

• npm run test:all – Executes the complete test suite including unit tests, Vitest tests, integration tests, E2E tests, protocol tests, and ecosystem compatibility checks.

• npm run test:unit – Runs only the Node-native unit tests using node --test for fast feedback during development.

• npm run test:vitest – Executes the Vitest suite covering MCP server functionality and auto-combo features.

• npm run test:e2e – Runs Playwright end-to-end tests using the configuration at scripts/e2e/playwright.config.ts.

• npm run test:protocols:e2e – Executes protocol-level E2E tests for all supported transports including STDIO, SSE, and HTTP.

• npm run test:integration – Runs integration tests located under tests/integration.

• npm run test:ecosystem – Runs compatibility tests against external ecosystems to ensure interoperability.

• npm run test:coverage – Generates code coverage reports after the full test run, utilizing scripts/coverage.mjs for report generation.

# Run all tests (comprehensive CI check)

npm run test:all

# Quick unit test feedback

npm run test:unit

# Run E2E suite with Playwright

npm run test:e2e

# Generate coverage reports

npm run test:coverage

Supporting Build Utilities

Several auxiliary scripts support the main build processes:

• scripts/check-fabricated-docs.mjs – Used by npm run check to verify documentation accuracy and prevent stale documentation from shipping.

• scripts/coverage.mjs – Handles coverage report generation invoked by the test:coverage script.

• scripts/cli/tsconfig.json – TypeScript configuration specifically for the CLI build process referenced by build:cli.

Summary

• OmniRoute centralizes all build automation in the root package.json file, providing 20+ scripts for every development phase.
• Development workflows use dev for hot-reloading and build:release for production artifacts with git SHA tracking.
• Quality gates combine lint, typecheck:noimplicit:core, and check to enforce code standards before commits.
• Desktop distribution relies on electron:build which embeds web assets into native binaries using scripts/electron/build.mjs.
• Testing coverage spans from fast test:unit feedback to comprehensive test:all suites including Playwright E2E and ecosystem compatibility checks.

Frequently Asked Questions

What is the difference between npm run build and npm run build:release in OmniRoute?

The build script produces a standard Next.js production bundle suitable for immediate deployment, while build:release performs additional steps required for official releases: it executes a clean rebuild, writes the current git SHA to dist/BUILD_SHA for version tracking, and ensures the bundle meets release criteria. Use build for local testing and build:release when preparing distribution artifacts.

How do I run type checking with strict settings in OmniRoute?

Execute npm run typecheck:noimplicit:core to enable strict TypeScript checking with no implicit any enforcement across the entire codebase. For faster feedback during development with relaxed strictness, use npm run typecheck:core instead. Both commands target the core modules as defined in the package.json scripts section.

What script should I use to package the OmniRoute desktop application?

Use npm run electron:build to generate the Electron binary for your current operating system. This script processes the web assets through the Next.js build pipeline first, then packages them into a standalone desktop application using the build logic in scripts/electron/build.mjs. For development testing, use npm run electron:dev instead to enable hot-reloading.

How can I run the full test suite before submitting a pull request?

Execute npm run check to run both linting and the complete test suite, or use npm run test:all specifically for testing. The check command combines npm run lint && npm run test:all, ensuring code quality and test coverage meet the repository standards. For coverage reports, follow up with npm run test:coverage.

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