How to Build Motrix from Source: Complete Development Guide

Motrix requires Node.js 22+ and pnpm to build from source, using a three-step workflow of dependency installation, Vite compilation for four process targets, and native-host packaging to produce cross-platform Electron binaries.

Motrix is a modern download manager built on Electron, React, and TypeScript. Building Motrix from source allows you to customize the aria2 download engine, modify the React-based user interface, or contribute to the core Electron application. This guide walks through the exact build process as defined in the agalwood/Motrix repository, including the specific Vite configurations and native compilation steps required to reproduce the official binaries.

Prerequisites for Building Motrix

Before compiling, ensure your environment meets the requirements specified in package.json at the repository root.

• Node.js 22+: The build system requires modern Node.js features for the Vite-based pipeline.
• pnpm: The project uses pnpm as its package manager, with the exact version declared in package.json.
• Platform tools: The build script automatically downloads the correct aria2 binary for your operating system and compiles the native-host wrapper without manual intervention.

Step-by-Step Build Process

Building Motrix follows a streamlined three-step workflow orchestrated through npm scripts.

1. Clone the Repository

Start by cloning the official source:

git clone https://github.com/agalwood/Motrix.git
cd Motrix

2. Install Dependencies

Run pnpm install to resolve all npm packages, pull the pre-built aria2 binary, and rebuild any native modules:

pnpm install

This command automatically handles the platform-specific aria2 engine download and prepares the native-host wrapper for compilation as defined in the repository's dependency tree.

3. Compile the Application

Execute pnpm build to trigger the full compilation sequence:

pnpm build

This command runs Vite builds for the main process, preload script, worker, and renderer, then packages the native-host via packages/native-host/build.mjs. Final artifacts are placed in the dist folder.

Development and Testing Workflow

After building, you can run the application in development mode or execute the test suite to verify functionality.

Run the Development Build

Launch Electron with hot-module reload using:

pnpm start

Execute Tests

Verify your build with the included test suites:

pnpm test       # Unit tests via Vitest

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

Key Build Configuration Files

Understanding these core files helps troubleshoot build issues or customize the compilation process.

package.json: Defines the pnpm version, Node.js engine requirements, and build scripts. It also declares dependencies for the aria2 fork used by the download engine.

vite.main.config.ts: Orchestrates bundling of the Electron main process and integrates the native-host build into the pipeline.

vite.renderer.config.ts: Configures the Vite build for the React-based UI bundle loaded by the Electron window.

vite.preload.config.ts: Compiles the preload script that exposes the window.motrix IPC bridge between main and renderer processes.

packages/native-host/build.mjs: The native-host build script that compiles the wrapper around the bundled aria2 engine and handles platform-specific packaging tasks.

electron-builder.json: Defines platform-specific installers (.dmg, .exe, .AppImage) and packaging rules for distribution.

Building the Native Host Manually

If you need to customize the native wrapper for the aria2 engine rather than using the auto-compiled version, build it separately:

cd packages/native-host
pnpm run build

This invokes packages/native-host/build.mjs directly, allowing modifications to how the native host interacts with the aria2 binary before repackaging the full application.

Summary

• Requirements: Node.js 22+ and pnpm are mandatory; the build system auto-downloads platform-specific aria2 binaries during installation.
• Core workflow: Run pnpm install followed by pnpm build to generate production-ready binaries in the dist folder.
• Architecture: The build compiles four Vite targets (main, preload, worker, renderer) plus the native-host wrapper that manages the aria2 engine.
• Customization: Modify packages/native-host/build.mjs to change native-host behavior, or edit the Vite configs to adjust bundling settings for specific platforms.

Frequently Asked Questions

What version of Node.js is required to build Motrix?

Motrix requires Node.js 22 or higher, as specified in the engine requirements within package.json. The build pipeline uses modern Node.js features for the Vite-based compilation system that bundles the Electron main process and React renderer.

Does building from source require manual installation of aria2?

No. Running pnpm install automatically downloads the correct pre-built aria2 binary for your platform and compiles the native-host wrapper. Manual intervention is only needed if you specifically want to modify the native-host source code in packages/native-host/ before running the build.

How do I create distributable installers after building?

Once pnpm build completes and outputs files to the dist folder, you can generate platform-specific installers using Electron-Builder. The configuration in electron-builder.json defines targets for .dmg (macOS), .exe (Windows), and .AppImage (Linux).

Can I run Motrix in development mode without building the full application?

Yes. Use pnpm start to launch Electron with hot-module reloading enabled. This command skips the full packaging step defined in electron-builder.json and is useful for iterative UI development and testing changes to the React renderer without generating final binaries.

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