tauri（Tauri 桌面开发）

Tauri v2 Development Skill

Build cross-platform desktop and mobile apps with web frontends and Rust backends using Tauri v2.

Core Principles

• Architecture: Use Rust for the backend (performance, native APIs) and any web framework for the frontend (UI, routing).
• Communication: Use Tauri's IPC (invoke, events, channels) to bridge the Rust backend and the web frontend.
• Security-First: Everything is denied by default. Explicitly configure permissions in src-tauri/capabilities/ to allow frontend access to backend commands and plugins.
• Cross-Platform: Write once, compile to Windows, macOS, Linux, Android, and iOS. Use lib.rs for shared logic.

Quick Setup Checklist

Before making changes to a Tauri project, verify:

• src-tauri/tauri.conf.json has build.devUrl and build.frontendDist configured.
• src-tauri/capabilities/default.json exists and includes necessary permissions.
• All custom Rust commands are registered in tauri::generate_handler![] within lib.rs or main.rs.
• lib.rs contains shared code, essential for mobile builds.

Primary Workflows

Creating and Using Commands

1. Define the command in Rust with #[tauri::command]: // src-tauri/src/lib.rs #[tauri::command] fn greet(name: String) -> Result<String, String> {Ok(format!("Hello, {}!", name))}
2. Register the command in tauri::Builder: tauri::Builder::default().invoke_handler(tauri::generate_handler![greet]) //...
3. Invoke the command from the frontend: import {invoke} from '@tauri-apps/api/core'; const response = await invoke<string>('greet', {name: 'World'});

For more detailed IPC patterns (async, error handling, events, channels), see ipc.md.

Managing Application State

1. Define state struct with thread-safe types (e.g., Mutex): use std::sync::Mutex; struct AppState {counter: Mutex<u32>}
2. Register state in the builder: tauri::Builder::default().setup(|app| {app.manage(AppState {counter: Mutex::new(0)}); Ok(())})
3. Access state in commands: #[tauri::command] fn increment(state: tauri::State<'_, AppState>) -> Result<u32, String> {let mut count = state.counter.lock().map_err(|e| e.to_string())?; *count += 1; Ok(*count)}

Configuring Security and Capabilities

Tauri v2 requires explicit capabilities for all IPC commands, including custom ones and core plugins.

For a complete guide to capabilities, see capabilities.md.

Configuration and Build Settings

Manage project settings, icons, plugins, and build commands in tauri.conf.json.

For tauri.conf.json and Cargo.toml configurations, see config.md.

Critical Rules

• Always register commands: Commands not in generate_handler![] fail silently on the frontend.
• Never use borrowed types in async commands: Use owned types (String, not &str). Async commands cannot borrow data across await points.
• Never block the main thread: Use async or std::thread::spawn for heavy I/O operations.
• Always handle errors explicitly: Return Result<T, AppError> from commands where AppError implements serde::Serialize.
• Always use @tauri-apps/api/core: The @tauri-apps/api/tauri path is deprecated from v1.

Troubleshooting

• "Command not found" / Promise hangs: Check if the command is added to generate_handler![]. Ensure frontend parameter names are camelCase and Rust parameters are snake_case.
• "Permission denied": The command or plugin lacks a capability in src-tauri/capabilities/.
• White screen on launch: Ensure the frontend dev server is running and matches build.devUrl in tauri.conf.json. Check beforeDevCommand.
• Mobile build fails: Ensure Rust targets are installed (rustup target add aarch64-linux-android...) and that the app logic is in lib.rs rather than main.rs.