Clash Verge Developer Docs

Note A UI symptom does not necessarily indicate a frontend fault. Trace the feature through the React interface, Tauri / Rust application layer and Mihomo core before locating the issue. System integration and privileged operations belong to the desktop layer; proxy and routing behavior belong 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 pnpm setup so the lockfile and dependency state match the project.

3. Prepare Mihomo and Runtime Assets

   Run prebuild to prepare the Mihomo core and service / sidecar resources required by the current platform.

4. Start Development Mode

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

5. Generate a Platform Build

   Use pnpm build for the standard Tauri build or pnpm build:fast for a faster local test build. Output paths depend on the active target and Tauri bundle configuration.

# 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 process
└─ UPDATELOG.md            # Project update log

Note This is an orientation map rather than a frozen contract. The current i18n process 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 rather than fixed values from an 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. Define the Change Scope

   Keep each change focused on one problem or feature area. Avoid mixing unrelated refactors, formatting changes 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. Keep Commits Focused

   Keep commit messages and diffs focused enough that reviewers can connect each changed area to the problem being addressed. Follow the repository's current signing requirements.

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. Include the verification details required by the current contribution guidance in the pull request body.

Caution The repository applies its current contribution requirements to commit signing, scope and verification. 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. A locally built binary should be identified by its source commit, build settings and signing state.