How to Set Up the Development Environment for Clash Nyanpasu with Rust and Node.js

To set up the development environment for Clash Nyanpasu, install Rust (≥1.78 stable with nightly toolchain), Node.js (≥20 LTS), pnpm (≥9), and system dependencies including CMake and LLVM, then run pnpm i and pnpm prepare:check before starting the dev server with pnpm dev:diff.

Clash Nyanpasu is a Tauri-based GUI application that combines a Rust backend with a modern JavaScript/TypeScript frontend. Setting up the development environment for Clash Nyanpasu requires configuring both the Rust toolchain and Node.js ecosystem, along with several platform-specific build tools required by native dependencies.

Prerequisites for Clash Nyanpasu Development

Before cloning the repository, ensure your system meets the following requirements specified in CONTRIBUTING.md.

Rust Toolchain

Clash Nyanpasu requires Rust ≥ 1.78 (stable). However, the project pins the nightly toolchain via rust-toolchain.toml for specific Tauri features.

Install Rust using rustup:

rustup install stable
rustup default stable

On Windows, ensure you use the MSVC toolchain. Verify your installation:

rustup show

This command reads rust-toolchain.toml and confirms you are on the nightly channel:

[toolchain]
channel = "nightly"

Node.js and Package Manager

The frontend requires Node.js ≥ 20 LTS and pnpm ≥ 9.

Install Node.js 20:

# Using nvm (recommended)

nvm install 20
nvm use 20

# Or download from nodejs.org

Enable pnpm via Corepack:

corepack enable
corepack prepare pnpm@latest --activate

System Build Dependencies

Several Rust crates require native compilation tools:

• CMake: Required by the zip crate used in the Rust backend
• LLVM: Needed by rquickjs and rocksdb crates
• patch (Windows only): Required by rquickjs; install via scoop install patch or similar

On Windows, run your first terminal session with administrator rights to allow patch installation, then use a normal shell for development work.

Clone the Repository and Install Dependencies

Once prerequisites are installed, clone the source code:

git clone https://github.com/libnyanpasu/clash-nyanpasu.git
cd clash-nyanpasu

Install Node Dependencies

Install all JavaScript/TypeScript packages defined in the monorepo's package.json:

pnpm i

This command installs UI libraries, TypeScript tooling, and the Tauri CLI required for development.

Download Clash Binaries with prepare:check

The application requires external Clash core binaries (e.g., clash-rs, mihomo) that are not included in the repository. Download these using:

pnpm prepare:check

To force a fresh download of all binaries:

pnpm prepare:check --force

This executes scripts/check.ts, which verifies and downloads the correct native binaries for your platform.

Start the Development Server

Clash Nyanpasu provides two development modes via scripts defined in package.json and configured in backend/tauri/tauri.conf.json.

Development Mode Options

pnpm dev:diff (Recommended for daily development)

Starts a dedicated development instance with hot-reload enabled for both Rust and frontend code. This mode is optimized for active coding and debugging.

pnpm dev

Starts a release-like Tauri dev window that behaves similarly to the shipped application. Use this to test final behavior before building.

Run the recommended development server:

pnpm dev:diff

Build the Application for Production

When ready to create distributable binaries:

# Standard release build

pnpm build

# Build with debug flags

pnpm build:debug

# Nightly-channel build (uses special Tauri config)

pnpm build:nightly

These commands invoke the Tauri CLI to compile the Rust backend and bundle the frontend assets into platform-specific installers.

Verify Your Rust Environment (Optional)

Confirm your Rust installation matches the project's requirements:

rustup show

This displays the active toolchain and should show the nightly channel as specified in rust-toolchain.toml.

Run Backend Tests (Optional)

Execute the Rust test suite to verify backend functionality:

pnpm test:backend

This runs cargo test against the Tauri backend code.

Summary

• Install Rust ≥ 1.78 (stable) and switch to the nightly toolchain via rust-toolchain.toml
• Install Node.js ≥ 20 LTS and pnpm ≥ 9 using Corepack
• Install system dependencies: CMake, LLVM, and patch (Windows only)
• Clone libnyanpasu/clash-nyanpasu and run pnpm i followed by pnpm prepare:check
• Start development with pnpm dev:diff for active coding or pnpm dev for release-like testing
• Build production binaries using pnpm build

Frequently Asked Questions

What version of Rust is required for Clash Nyanpasu?

Clash Nyanpasu requires Rust 1.78 or newer (stable channel). However, the project uses a rust-toolchain.toml file that pins the nightly toolchain to enable specific Tauri features. Running rustup show in the project directory will automatically install and activate the correct nightly version.

Can I use npm or yarn instead of pnpm?

No, pnpm is required. The monorepo structure and scripts in package.json are specifically configured for pnpm. The project requires pnpm version 9 or higher, which you can enable via Corepack (corepack enable && corepack prepare pnpm@latest --activate) or install directly from the pnpm website.

Why does Clash Nyanpasu require the nightly Rust toolchain?

The nightly Rust toolchain is required for specific Tauri features and dependencies used in the project. The rust-toolchain.toml file at the repository root explicitly sets channel = "nightly" to ensure compatibility with the Tauri framework and certain Rust crates that require cutting-edge compiler features. This is enforced automatically when you run rustup show in the project directory.

How do I fix build errors related to CMake or LLVM on Windows?

Ensure you have installed CMake and LLVM as system dependencies. For patch (required by the rquickjs crate on Windows), install it via Scoop (scoop install patch) or another package manager. Run your initial terminal session with administrator rights to allow the installation of patch, then switch to a normal shell for development. If CMake or LLVM errors persist, verify they are in your system PATH environment variable.

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