# How to Contribute to the Motrix Project: A Complete Developer Guide

> Contribute to the Motrix project by forking the repository, installing dependencies, and submitting a pull request. Follow this developer guide to get started.

- Repository: [Dr_rOot/Motrix](https://github.com/agalwood/Motrix)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Fork the agalwood/Motrix repository, install dependencies with pnpm, and submit a pull request that passes Biome linting and Vitest/Playwright test suites.**

Motrix is an open-source download manager built with **Electron**, **React**, and **TypeScript** that welcomes community contributions. Whether you are fixing bugs, adding UI components, or extending the plugin system, understanding how to contribute to the Motrix project ensures your changes integrate smoothly with the codebase. This guide walks through the complete development setup, architecture overview, and submission workflow based on the official repository structure.

## Prerequisites and Repository Setup

Before writing code, ensure your environment meets the project requirements. Motrix requires **Node.js 22+** and uses **pnpm** as its package manager.

Start by forking the repository and cloning your copy:

```bash
git clone https://github.com/<your-username>/Motrix.git
cd Motrix

```

The project enforces strict TypeScript settings and uses a monorepo-style structure with multiple Vite configurations for different Electron processes.

## Installing Dependencies and First Run

Run the installation command to download development dependencies, the bundled aria2 engine, and rebuild native modules:

```bash
pnpm install

```

This command triggers scripts defined in [[`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json)](https://github.com/agalwood/Motrix/blob/main/package.json) that prepare the native C++ aria2 binaries and QuickJS sandbox environment. Once complete, launch the application in development mode with hot-module replacement:

```bash
pnpm start

```

The `start` script initializes the Electron main process, preload scripts, and React renderer simultaneously using separate Vite configurations defined in [[`vite.main.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.main.config.ts)](https://github.com/agalwood/Motrix/blob/main/vite.main.config.ts), [[`vite.preload.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.preload.config.ts)](https://github.com/agalwood/Motrix/blob/main/vite.preload.config.ts), and [[`vite.renderer.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.renderer.config.ts)](https://github.com/agalwood/Motrix/blob/main/vite.renderer.config.ts).

## Understanding the Motrix Architecture

The codebase follows a layered architecture that separates UI, business logic, and download engine concerns. When you contribute to the Motrix project, you will work within one of these four layers:

### Renderer Layer (React UI)

The front-end interface resides in `src/renderer/` and is built with **React 19**, **Tailwind CSS 4**, and **shadcn/ui**. This layer handles all user interactions and communicates with the main process via Electron's IPC bridge. Configuration for this layer is managed in [`vite.renderer.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.renderer.config.ts).

### App Core and IPC Bridge

Business logic for tasks, settings, and plugin management lives in `src/app/` and `src/main/`. These modules coordinate between the UI and the download engine, managing state persistence and sandboxed plugin execution. The IPC bridge ensures secure communication between the renderer and Node.js processes.

### Engine Adapter

The `src/engine/` directory contains glue code that adapts the bundled aria2 download engine to the application's JavaScript interface. This layer translates high-level download tasks into aria2 RPC calls and handles progress reporting.

### Aria2 Engine

Motrix bundles a forked version of aria2 (native C++) compiled for each platform. Configuration files and build scripts reside in [`extra/aria2.conf`](https://github.com/agalwood/Motrix/blob/main/extra/aria2.conf) and associated native build directories. Unless you are specifically modifying the download core, you typically will not need to rebuild this layer.

## Development Workflow and Code Quality

Maintaining code quality is mandatory for all contributions. The project uses **Biome** for TypeScript linting and formatting, and all PRs must pass automated checks defined in [[`.github/workflows/ci.yml`](https://github.com/agalwood/Motrix/blob/main/.github/workflows/ci.yml)](https://github.com/agalwood/Motrix/blob/main/.github/workflows/ci.yml).

### Running the Test Suite

Validate your changes using the dual testing strategy:

```bash
pnpm test        # Vitest unit tests

pnpm test:e2e    # Playwright end-to-end tests

```

Vitest handles unit testing for utility functions and store logic, while Playwright executes integration tests across the Electron application window.

### Linting and Formatting

Before committing, ensure your code adheres to the project's style guide:

```bash
pnpm run lint

```

Biome checks TypeScript files for formatting errors, import organization, and potential logic issues. The CI pipeline will reject PRs that fail these checks.

### Building Production Packages

Verify that your changes compile correctly for distribution:

```bash
pnpm build

```

This command generates platform-specific Electron packages and validates that the renderer, main process, and preload scripts bundle without errors.

## Submitting Your Contribution

Once your feature or fix is complete, follow the standard GitHub workflow to submit changes.

1. **Create a feature branch** isolated from `main`:

   ```bash
   git checkout -b my-feature
   ```

2. **Write clear commit messages** following conventional commit format (e.g., `feat: add torrent priority sorting`, `fix: correct download path validation`).

3. **Push to your fork** and open a Pull Request against `agalwood/Motrix:main`. The PR template will trigger CI checks for linting, testing, and building.

4. **Address review feedback** by pushing additional commits to your branch; the PR updates automatically.

5. **Sign the CLA** by affirming in your PR description that you have the right to contribute the code under the project's MIT license, as referenced in [`LICENSE`](https://github.com/agalwood/Motrix/blob/main/LICENSE).

Typical contributions include enhancing the plugin sandbox in `src/app/plugins/`, improving the aria2 adapter in `src/engine/`, or adding new UI components using the established Tailwind and shadcn/ui patterns.

## Summary

- **Fork and clone** the `agalwood/Motrix` repository using standard GitHub workflows.
- **Install dependencies** with `pnpm install`, which requires Node.js 22+ and automatically prepares native aria2 binaries.
- **Run development builds** using `pnpm start` to launch Electron with hot-reload capabilities across multiple Vite configurations.
- **Validate changes** with `pnpm test` (Vitest), `pnpm test:e2e` (Playwright), and `pnpm run lint` (Biome) before submitting.
- **Target the correct layer** when modifying code: `src/renderer/` for UI, `src/app/` for business logic, or `src/engine/` for download adapters.
- **Submit PRs** against the `main` branch with conventional commit messages and CLA confirmation to trigger automated CI checks.

## Frequently Asked Questions

### What are the minimum system requirements to contribute to Motrix?

You need **Node.js 22 or higher** and **pnpm** installed on your system. The development environment download approximately 500MB of dependencies including the aria2 native engine and Electron binaries. Windows, macOS, and Linux are all supported development platforms.

### How do I run tests before submitting a pull request?

Execute `pnpm test` to run the Vitest unit test suite covering utility functions and store logic. For integration testing, run `pnpm test:e2e` to launch Playwright tests that simulate user interactions in the actual Electron window. Both commands must pass before maintainers will merge your PR.

### What linting tools does the Motrix project use?

The project uses **Biome** (enforced via `pnpm run lint`) to check TypeScript formatting, import ordering, and code quality. Unlike ESLint/Prettier setups, Biome provides unified linting and formatting in a single tool, configured in the repository root.

### Is a Contributor License Agreement required for Motrix?

Yes, you must affirm that you have the right to contribute your code under the MIT license. This is done by including a simple statement in your Pull Request description acknowledging the license terms found in [`LICENSE`](https://github.com/agalwood/Motrix/blob/main/LICENSE). No external CLA signing service is required.