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

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:

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:

pnpm install

This command triggers scripts defined in [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:

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), [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).

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.

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 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).

Running the Test Suite

Validate your changes using the dual testing strategy:

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:

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:

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:

   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.

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. No external CLA signing service is required.

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