Setting up the development environment and build process for Clash Verge Rev

Clone the repository, install Node.js ≥18 and Rust stable, run pnpm i and pnpm run prebuild to download the mihomo sidecar, then launch the development server with pnpm dev to start hacking on this Rust/Tauri 2 and React 19 desktop application.

Clash Verge Rev is a modern desktop GUI for the Clash Meta proxy core that combines a high-performance Rust/Tauri 2 backend with a React 19 frontend built by Vite. Setting up the development environment for Clash Verge Rev requires configuring both the Node.js toolchain for the UI and the Rust toolchain for the native backend, plus running a pre-build script that downloads the necessary sidecar binaries. This guide walks you through the complete setup process, from cloning the repository to building production releases.

Architecture Overview

Understanding the three-layer architecture helps clarify why specific setup steps are required.

Backend Layer (Rust/Tauri 2)

The backend handles windowing, native APIs, and sidecar binaries (the mihomo core and service helpers). Key files include [Cargo.toml](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/Cargo.toml) for workspace definition and the src-tauri/ directory for Rust source code and Tauri configuration.

Frontend Layer (React 19 + Vite)

The UI is a React 19 application using TypeScript. The entry point is [src/main.tsx](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/src/main.tsx), while vite.config.mts handles the build configuration. State management uses context providers in src/providers/, and internationalization uses react-i18next with locales in src/locales/.

Glue Layer (Pre-build Scripts)

scripts/prebuild.mjs bridges the layers by downloading the mihomo binary, GeoIP/GeoSite databases, and platform-specific resources before compilation.

Prerequisites

Before cloning the repository, ensure your system meets these requirements:

• Node.js ≥ 18 (LTS recommended)
• pnpm ≥ 10 (the project uses pnpm workspaces)
• Rust stable toolchain (install via rustup)
• Tauri prerequisites (OS-specific dependencies like WebView2 on Windows, or Xcode on macOS; see the official Tauri guide)

Initial Setup and Installation

Once prerequisites are installed, configure the project with these commands:

# 1. Clone the repository

git clone https://github.com/clash-verge-rev/clash-verge-rev.git
cd clash-verge-rev

# 2. Install Node dependencies

pnpm i

# 3. Install Rust dependencies (handled automatically by Tauri, but ensure toolchain is set)

rustup toolchain install stable
rustup default stable

# 4. Run the pre-build script to download sidecars and resources

pnpm run prebuild

The pnpm run prebuild command executes node scripts/prebuild.mjs, which is essential because the Clash Meta core (mihomo) is not compiled from source; instead, a pre-built binary is downloaded and placed in src-tauri/sidecar (or src-tauri/resources for non-Linux platforms).

Understanding the Pre-build Script

The scripts/prebuild.mjs script automates the acquisition of external binaries and databases required for runtime.

What It Downloads

• mihomo core: The Clash Meta proxy engine binary
• GeoIP/GeoSite databases: IP and domain classification data
• Windows service plugin: Helper for system-level proxy configuration on Windows
• Enable-loopback utility: For handling localhost routing on Windows

Caching Mechanism

The script maintains two cache files to avoid redundant network calls:

• .verge/.version_cache.json: Tracks downloaded versions
• .verge/.hash_cache.json: Stores file hashes for integrity verification

To force a fresh download, run pnpm run prebuild --force.

Sidecar Placement

Downloaded binaries are organized as follows:

src-tauri/
├── sidecar/          # Linux sidecar binaries

└── resources/        # Windows and macOS resources

Development Workflow

With the environment configured, start the development server:

pnpm dev

This command (defined in package.json as tauri dev -f verge-dev) launches:

1. Vite development server: Hot-reloading React UI on a local port
2. Tauri development mode: Rust backend compiled with debug symbols and connected to the Vite dev server

Project Structure for Development

When modifying code, navigate these key directories:

• src/components/: Reusable UI components
• src/pages/: Route-based page components (home, settings, profiles, logs)
• src/providers/: Global state contexts (app-data-provider, window-provider)
• src-tauri/src/: Rust source code for native APIs and window management

Cleaning Up Resources

When implementing features that use WebSockets or native resources, ensure proper cleanup. For example, in [src/main.tsx](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/src/main.tsx):

import { MihomoWebSocket } from "tauri-plugin-mihomo-api";

window.addEventListener("beforeunload", () => {
  // Clean up all WebSocket instances to avoid memory leaks
  MihomoWebSocket.cleanupAll();
});

Building for Production

When ready to distribute the application, use the production build commands:

# Standard production build with optimizations

pnpm build

# Fast release build (skips code-size optimization, faster compilation)

pnpm build:fast

These commands execute tauri build (configured in vite.config.mts), which:

1. Compiles the React frontend into optimized static assets
2. Compiles the Rust backend in release mode
3. Bundles sidecars and resources into the final executable
4. Generates platform-specific installers

Output Locations

After building, find the distributables in:

src-tauri/target/release/bundle/
├── *.msi          # Windows installer

├── *.dmg          # macOS disk image

├── *.AppImage     # Linux portable executable

└── *.deb          # Linux Debian package (if configured)

Summary

Setting up the Clash Verge Rev development environment involves configuring a dual-stack toolchain:

• Install prerequisites: Node.js ≥18, pnpm ≥10, Rust stable, and Tauri system dependencies
• Clone and install: Use git clone, pnpm i, and rustup to prepare the workspace
• Run pre-build: Execute pnpm run prebuild to download the mihomo sidecar and GeoIP databases to src-tauri/sidecar and src-tauri/resources
• Develop: Use pnpm dev to start hot-reloading development with Vite and Tauri
• Build: Use pnpm build to generate release binaries and installers in src-tauri/target/release/bundle/

Frequently Asked Questions

What is the purpose of the pre-build script in Clash Verge Rev?

The scripts/prebuild.mjs script downloads external dependencies that are not compiled from source, including the mihomo (Clash Meta) core binary, GeoIP/GeoSite databases, and platform-specific utilities like the Windows service plugin. It caches these files in .verge/.version_cache.json and .verge/.hash_cache.json to avoid redundant downloads, placing binaries in src-tauri/sidecar (Linux) or src-tauri/resources (other platforms).

Why does the development server require both Node.js and Rust toolchains?

Clash Verge Rev uses a hybrid architecture where the frontend is a React 19 application built with Vite (requiring Node.js ≥18 and pnpm), while the backend is a Rust application using the Tauri 2 framework (requiring the Rust stable toolchain). The pnpm dev command orchestrates both environments, starting the Vite development server for hot-reloading UI components while compiling and running the Rust backend in debug mode.

How do I force a fresh download of the sidecar binaries?

Run the pre-build script with the --force flag: pnpm run prebuild --force. This bypasses the caching mechanism (which normally checks .verge/.version_cache.json and .verge/.hash_cache.json) and re-downloads the mihomo core, GeoIP databases, and auxiliary resources regardless of existing local copies.

Where are the production build artifacts located after compilation?

After running pnpm build or pnpm build:fast, the distributable files are generated in src-tauri/target/release/bundle/. This directory contains platform-specific installers such as .msi files for Windows, .dmg images for macOS, and .AppImage or .deb packages for Linux, depending on your target platform configuration.

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