Clash Verge Developer Guide

Note A UI symptom does not always mean a frontend bug. Trace the feature through the React interface, Tauri/Rust application layer and Mihomo core before deciding where the fault lives. System integration and privileged operations belong to the desktop layer; proxy behavior belongs to Mihomo.

Caution The current contribution guide lists Ubuntu packages such as libwebkit2gtk-4.1-dev, libayatana-appindicator3-dev, librsvg2-dev and patchelf. Other distributions use different package names, so follow the error and your platform's Tauri requirements.

1. Clone the repository

   Get the source and change into the project directory.

2. Install Project Dependencies

   Enable Corepack and use the repository's pinned pnpm workflow instead of introducing a different package manager.

3. Download Mihomo and Runtime Assets

   Run the prebuild script to download the Mihomo core and service/sidecar binaries required by the current platform.

4. Start the Development Shell

   pnpm dev is the standard development command. The repository also exposes pnpm dev:diff and pnpm dev:tauri for specific development cases.

5. Build the Application

   Use pnpm build for the standard Tauri build or pnpm build:fast for a faster testing build. Final artifact locations depend on the active target and Tauri bundle output.

# 1. Clone the repository
git clone https://github.com/clash-verge-rev/clash-verge-rev.git
cd clash-verge-rev

# 2. Enable Corepack and install dependencies
corepack enable
pnpm install

# 3. Download Mihomo and service binaries
pnpm run prebuild
# Re-download and overwrite them when needed:
# pnpm run prebuild --force

# 4. Start development
pnpm dev
# Alternatives:
# pnpm dev:diff
# pnpm dev:tauri

# 5. Build the current platform
pnpm build
# Faster test build:
# pnpm build:fast

Note The dev branch currently defines prebuild, dev, dev:diff, dev:tauri, build and build:fast in package.json. Check that file again when working against a different commit or release branch.

clash-verge-rev/
├─ src/                    # React + TypeScript frontend
├─ src-tauri/              # Tauri 2 + Rust desktop application
│  ├─ src/                 # Rust application and system integration
│  ├─ resources/           # Runtime resources
│  ├─ sidecar/             # Mihomo and related sidecar binaries
│  ├─ Cargo.toml           # Rust dependencies
│  └─ tauri.conf.json      # Tauri app and bundle configuration
├─ scripts/                # Prebuild, release and development scripts
├─ .github/                # CI and GitHub Actions
├─ package.json            # pnpm scripts and frontend dependencies
├─ CONTRIBUTING.md         # Current development and contribution workflow
└─ UPDATELOG.md            # Project update log

Note This is an orientation map rather than a frozen contract. The current i18n workflow uses locale folders under src/locales/<lang>/ for frontend strings and separate backend locale files, so follow CONTRIBUTING_i18n.md when a change affects translated copy.

import { invoke } from "@tauri-apps/api/core";
import { listen } from "@tauri-apps/api/event";

// Example only: use command and event names from the current source tree
const result = await invoke("command_name", {
  payload: { key: "value" },
});

const unlisten = await listen("event-name", (event) => {
  console.log(event.payload);
});

// Stop listening when the component or view is disposed
unlisten();

// Example only: expose a Rust function as a Tauri command
#[tauri::command]
fn command_name(payload: serde_json::Value) -> Result<serde_json::Value, String> {
    Ok(payload)
}

fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![command_name])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Caution These snippets explain the Tauri IPC model, not the current Clash Verge command registry. Trace the frontend call site to the corresponding Rust command, event and data type before implementing or documenting a feature.

# Example only: replace with the controller address used by your running profile
BASE=http://127.0.0.1:9090
AUTH="Authorization: Bearer your-secret"

# Version and current runtime config
curl -H "$AUTH" "$BASE/version"
curl -H "$AUTH" "$BASE/configs"

# Change runtime mode: rule / global / direct
curl -X PATCH -H "$AUTH" -d '{"mode":"rule"}' "$BASE/configs"

# Proxy groups and active connections
curl -H "$AUTH" "$BASE/proxies"
curl -H "$AUTH" "$BASE/connections"

# Live traffic and logs can also be consumed over WebSocket
# ws://127.0.0.1:9090/traffic?token=your-secret
# ws://127.0.0.1:9090/logs?level=info&token=your-secret

Caution Treat the controller URL and secret as runtime configuration, not constants copied from a documentation example. An exposed controller can change proxy behavior and inspect runtime state, so bind it conservatively and protect it with authentication when appropriate.

Note Paths and application identifiers can differ by platform or build channel. Prefer the client's own app-directory and log-directory shortcuts when available, and back up important data before testing migrations or manual file edits.

1. Start from a Real Issue

   Non-trivial changes should map to a pre-existing issue. Keep the implementation focused on that problem instead of mixing unrelated refactors, formatting churn or dependency updates into the same pull request.

2. Fork and create a branch

   One branch, one thing, with a name that states the intent — for example fix/tray-menu-crash.

3. Run the Required Checks

   Run cargo clippy-all for Rust, pnpm lint for the frontend, then format with cargo fmt and pnpm format. Also reproduce the reported behavior and verify the actual fix.

4. Use Signed, Focused Commits

   Commits must be signed. Keep messages and diffs focused enough that reviewers can connect each changed area to the issue being solved.

5. Explain Verification in the Pull Request

   Describe the problem in your own words, show how you reproduced and verified it, and include screenshots when UI behavior changes. If AI automation produced or co-produced the change, disclose that assistance in the pull request body.

Caution The repository requires signed commits and currently reviews contributor pull requests for scope, ownership and verification quality. GPL-3.0 licensing still applies, and new dependencies should have a clear technical reason and a compatible license.

Note Application release channels and Mihomo core channels are different layers. A Clash Verge AutoBuild is not the same thing as switching the bundled Mihomo core to its Alpha channel. When sharing a self-built binary, label its source clearly so users know which commit, build settings and signing process produced it.