How to Contribute to OmniRoute Development: A Complete Guide

Yes, OmniRoute actively accepts contributions through its MIT‑licensed GitHub repository, provided you follow the structured workflow defined in CONTRIBUTING.md, maintain strict TypeScript and ESLint standards, and include comprehensive tests and documentation for every change.

OmniRoute is an open‑source unified AI proxy and router supporting over 237 LLM providers, MCP tools, and A2A JSON‑RPC services. If you want to contribute to OmniRoute development, you will work within a Next.js App Router architecture that uses a streaming engine (open‑sse/), a SQLite data layer (src/lib/db/), and a modular executor pattern for provider integrations.

Prerequisites and Development Setup

Before you contribute to OmniRoute, ensure your local environment meets the baseline requirements. The project requires Node.js ≥ 22 (or 24) and uses TypeScript 6.0 for type safety.

Install dependencies using the lockfile to ensure reproducible builds:

npm ci

Verify your setup by running the linting and formatting checks:

npm run lint
npm run prettier

Contribution Workflow

The canonical workflow for contributing to OmniRoute is documented in the repository’s [CONTRIBUTING.md](https://github.com/diegosouzapw/OmniRoute/blob/main/CONTRIBUTING.md) file. The process follows standard GitHub practices:

1. Fork the repository to your personal GitHub account.
2. Clone your fork and create a feature branch: git checkout -b feat/your-feature-name.
3. Implement your changes following the code style and architecture patterns described below.
4. Run the full test suite: npm run test:all.
5. Update relevant documentation in the docs/ directory.
6. Commit with clear, descriptive messages and push to your fork.
7. Open a Pull Request against the upstream main branch.

All pull requests undergo automated CI checks for linting, type safety, and security scanning before maintainer review.

Code Standards and Quality Gates

OmniRoute enforces strict code quality through Prettier and ESLint. The configuration mandates 2‑space indentation, semicolons, double quotes, and path aliases (@/ maps to src/).

Key requirements include:

• TypeScript strictness: All new code must pass strict type checking.
• Naming conventions: Use descriptive variable names and PascalCase for classes (e.g., AcmeExecutor).
• No trailing spaces or unused imports.

Run quality checks before committing:

npm run lint && npm run prettier

Where to Contribute Code

Depending on your contribution type, you will modify specific architectural layers:

Adding New LLM Providers

To integrate a new provider (e.g., "AcmeAI"), modify three core files:

1. src/shared/constants/providers.ts: Add the provider identifier to the Zod‑validated enum.
2. open-sse/executors/: Create a new executor class (e.g., acme.ts) extending BaseExecutor to handle provider‑specific request formatting.
3. open-sse/config/providerRegistry.ts: Register the executor with its metadata (base URL, auth header pattern).

Extending API Routes

New REST endpoints belong in the Next.js App Router structure under src/app/api/v1/. Follow the existing pattern in chat/completions/route.ts, ensuring you export a default handler function and apply appropriate middleware for authentication and validation.

Database Schema Changes

Persistence logic resides in src/lib/db/. Add new table modules here and create corresponding migration scripts in db/migrations/. The project uses SQLite, so ensure your migrations are idempotent and backward‑compatible where possible.

MCP Tools and Skills

To add a new skill or MCP tool, implement the handler in open-sse/mcp-server/tools/ and register it in open-sse/mcp-server/index.ts. Tools must follow the JSON‑RPC 2.0 specification for A2A compliance.

Testing Requirements

Every contribution must include comprehensive test coverage. The project uses Vitest for unit tests, Playwright for end‑to‑end testing, and custom protocol validators.

Run the complete test matrix:

npm run test:all

For protocol‑specific validation:

npm run test:protocols:e2e

Unit tests for executors should reside in tests/unit/ and verify request building, error handling, and response parsing. Integration tests must validate the full request lifecycle through the Next.js API routes.

Documentation Obligations

OmniRoute requires that every public change—new API endpoints, environment variables, or Zod schemas—be reflected in the documentation. The CI enforces this via:

npm run check:fabricated-docs

Update the relevant Markdown files in docs/ (e.g., docs/reference/PROVIDER_REFERENCE.md for new providers) and the main [README.md](https://github.com/diegosouzapw/OmniRoute/blob/main/README.md) if adding major features.

Practical Example: Adding a Provider

Below is a complete workflow for contributing a fictional "AcmeAI" provider:

# Fork and clone

git clone https://github.com/<your-username>/OmniRoute.git
cd OmniRoute

# Install dependencies

npm ci

# Create feature branch

git checkout -b feat/acme-provider

# 1. Update provider constants

# Edit: src/shared/constants/providers.ts

# Add: export const PROVIDERS = z.enum([..., "acme"]);

# 2. Implement executor

# Create: open-sse/executors/acme.ts

# export class AcmeExecutor extends BaseExecutor { ... }

# 3. Register provider

# Edit: open-sse/config/providerRegistry.ts

# register("acme", AcmeExecutor, { baseUrl: "...", authHeader: "X-Acme-Key" });

# 4. Add unit tests

# Create: tests/unit/acmeExecutor.test.ts

# Run tests

npm run test:all

# Lint and format

npm run lint && npm run prettier

# Update documentation

# Edit: docs/reference/PROVIDER_REFERENCE.md

# Edit: README.md

# Commit and push

git add .
git commit -m "feat: support AcmeAI provider"
git push origin feat/acme-provider

# Open PR on GitHub

Summary

• OmniRoute welcomes contributions via the standard GitHub fork‑and‑PR workflow defined in CONTRIBUTING.md.
• Development requires Node.js ≥ 22, strict TypeScript compliance, and adherence to Prettier/ESLint rules.
• Provider integrations require updates to src/shared/constants/providers.ts, open-sse/executors/, and open-sse/config/providerRegistry.ts.
• API routes belong in src/app/api/v1/ following the Next.js App Router pattern.
• Database changes require modules in src/lib/db/ and migration scripts in db/migrations/.
• All changes must include tests (npm run test:all) and documentation updates verified by npm run check:fabricated-docs.

Frequently Asked Questions

Is OmniRoute open to external contributors?

Yes, OmniRoute is an open‑source project under the MIT license hosted at diegosouzapw/OmniRoute. External contributors can submit pull requests for bug fixes, new providers, features, or documentation improvements, provided they follow the guidelines in CONTRIBUTING.md.

Which Node.js version is required to contribute to OmniRoute?

The project requires Node.js version 22 or higher (version 24 is also supported). You must use npm ci to install dependencies, ensuring exact versions from the lockfile are used to maintain build consistency across environments.

How do I add a new LLM provider to OmniRoute?

To add a provider, update the Zod enum in src/shared/constants/providers.ts, implement a request executor class in open-sse/executors/, and register the mapping in open-sse/config/providerRegistry.ts. You must also add unit tests and update the provider reference documentation.

What happens if my pull request fails the documentation check?

The CI runs npm run check:fabricated-docs to ensure every code change has corresponding documentation. If this check fails, you must update the relevant Markdown files in the docs/ directory or the README.md to describe your changes before the PR can be merged.

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