# How to Contribute to OmniRoute Development: A Complete Guide

> Contribute to OmniRoute development by following our GitHub guide. Ensure TypeScript, ESLint, tests, and documentation standards for your contributions.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-06

---

**Yes, OmniRoute actively accepts contributions through its MIT‑licensed GitHub repository, provided you follow the structured workflow defined in [`CONTRIBUTING.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
npm ci

```

Verify your setup by running the linting and formatting checks:

```bash
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)](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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/acme.ts)) extending `BaseExecutor` to handle provider‑specific request formatting.
3. **[`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
npm run test:all

```

For protocol‑specific validation:

```bash
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:

```bash
npm run check:fabricated-docs

```

Update the relevant Markdown files in `docs/` (e.g., [`docs/reference/PROVIDER_REFERENCE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/PROVIDER_REFERENCE.md) for new providers) and the main [[`README.md`](https://github.com/diegosouzapw/OmniRoute/blob/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:

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts), `open-sse/executors/`, and [`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts), implement a request executor class in `open-sse/executors/`, and register the mapping in [`open-sse/config/providerRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/README.md) to describe your changes before the PR can be merged.