Repository Guidelines

Project Overview

Frpc-Desktop is a cross-platform Tauri 2 desktop application. The webview UI uses Vue 3, TypeScript, Vite, Pinia, Vue Router, Element Plus, and vue-i18n. The Rust backend in src-tauri/ manages frpc processes, SQLite persistence, downloads, system integration, tray, autostart, and IPC.

Use Node.js 22.12 or newer, npm, and a stable Rust toolchain. Keep changes focused; do not edit generated output or downloaded dependencies.

Repository Layout

• src/: Vue webview application.
  • views/: route-level screens.
  • components/: shared UI components.
  • store/: Pinia stores and frontend application state.
  • lang/: English and Simplified Chinese translations.
  • core/IpcRouter.ts: canonical IPC route paths and event channels.
  • utils/ipcUtils.ts: frontend IPC helpers (invoke("ipc_send") and event listeners).
• src-tauri/: Tauri Rust backend.
  • src/lib.rs: application startup, data directory, window, tray, and autostart wiring.
  • src/commands/: ipc_send dispatcher that maps route paths to backend behavior.
  • src/db/: SQLite (rusqlite) connection, migration runner, and repositories.
  • migrations/: ordered SQLite migration files.
  • src/downloader/, src/process/, src/config_gen/, src/system/: frpc versions, frpc process, TOML generation, and OS integration.
  • src/models.rs: Rust payload models serialized to the frontend and JSON columns.
  • tauri.conf.json, capabilities/, icons/: Tauri app configuration and bundle assets.
• types/: global TypeScript declarations shared by frontend code.
• public/: static assets and logos.
• scripts/: npm helper scripts (for example run-tauri.mjs).
• screenshots/: README assets; do not update unless documentation visuals change.
• dist/, src-tauri/target/, and node_modules/: generated content; never hand-edit or commit newly generated files unless explicitly requested.

Common Commands

npm ci
npm run tauri:dev
npm run lint
npm run build
cd src-tauri && cargo test

npm run tauri:dev starts Vite and the Tauri development app. npm run dev starts only the Vite frontend; Tauri APIs are unavailable in a plain browser. npm run build runs vue-tsc --noEmit before the Vite production build. npm run tauri:build produces platform installers and is not a routine validation step.

For normal code changes, run lint, build, and the Rust tests. For UI or backend behavior changes, also exercise the affected workflow in the development app and report what was checked.

Architecture and Change Conventions

• Keep frontend code concerned with presentation and state. Filesystem, process, network, database, and OS behavior belong under src-tauri/.
• Follow the existing flow: frontend send(ipcRouters.X.y) -> ipc_send in src-tauri/src/commands/mod.rs -> repository/service -> ApiResponse returned to the :hook handler. Backend-pushed updates use Tauri events named by listeners in src/core/IpcRouter.ts.
• When adding IPC behavior, update all participating pieces: the route in src/core/IpcRouter.ts, the matching ipc_send branch, the Rust implementation, and frontend on/send calls. Remove listeners when component-scoped subscriptions can be recreated.
• Return results with ApiResponse::success / ApiResponse::fail and keep the existing bizCode conventions.
• Put shared frontend interfaces in types/; keep Rust models in src-tauri/src/models.rs serialized with the same JSON field names (use explicit serde(rename) when names are not plain camelCase, such as proxyURL).
• User-facing text must support both src/lang/en-US.ts and src/lang/zh-CN.ts. Preserve existing terminology for frp/frpc concepts.
• Preserve the current formatting style: two-space indentation, double quotes, semicolons, trailing commas only where Prettier adds them, and TypeScript/Vue conventions enforced by ESLint and Prettier. Format Rust with rustfmt conventions.
• Use the @/ alias for frontend imports.
• Do not introduce unrelated refactors, broad formatting churn, or dependency upgrades as part of a focused fix.

Data and Security

• Treat configuration, tokens, proxy definitions, logs, and local paths as sensitive. Do not log secrets or include real credentials in fixtures, screenshots, or examples.
• Preserve compatibility with existing user data: the app data directory (<config dir>/Frpc-Desktop), the SQLite database, Electron 1.x frpc binary names, and frpc configuration formats. Schema, path, or filename changes require an explicit migration or backward-compatible fallback.
• Keep the bundle identifier priv.liujiawei.frpc.desktop so installs upgrade in place.
• Validate frontend-provided IPC arguments in Rust before using them in paths, shell operations, downloads, or process commands.

Documentation and Commits

The canonical frontend UI development standard is docs/FRONTEND_UI_STANDARDS.md. Read and follow it before creating or changing renderer UI, layout, styling, interaction states, icons, or user-facing copy.

The canonical database design and migration document is docs/DATABASES.md. Read and follow it before changing persistence models, SQLite schema or migrations, repositories, database paths, or data compatibility behavior.

Update both README.md and README.zh_CN.md when changing user-facing setup or behavior. Keep commit subjects short and aligned with the repository's conventional emoji-prefixed history when practical (for example, 🐛 Fix ..., ✨ Add ..., or 🔧 Update ...). Do not commit build artifacts or local application data.