tauri-v2

What this skill does

# Tauri v2 Development Skill

Tauri v2 lets you build tiny, fast apps for desktop (macOS, Windows, Linux) and mobile (iOS, Android) by combining a web frontend with a Rust backend. Apps use the system's native webview instead of bundling a browser engine, so a minimal app can be under 600KB.

**Default stack in this skill:** React + Vite + TypeScript frontend, Rust backend. Adapt if the user specifies a different framework.

## Quick Reference

- Config file: `src-tauri/tauri.conf.json`
- Rust entry: `src-tauri/src/lib.rs` (or `main.rs`)
- Capabilities: `src-tauri/capabilities/*.json`
- Permissions: `src-tauri/permissions/*.toml`
- JS API: `@tauri-apps/api`
- CLI: `@tauri-apps/cli` (npm) or `tauri-cli` (cargo)

For detailed reference on configuration, plugins, permissions, and mobile setup, see the `references/` directory. Read the relevant file when you need specifics beyond what's covered here.

## Prerequisites

Before creating a Tauri project, ensure these are installed:

**All platforms:** Rust via rustup (`curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh`), Node.js LTS

**macOS:** Xcode or Xcode Command Line Tools (`xcode-select --install`)

**Windows:** Microsoft C++ Build Tools (select "Desktop development with C++"), WebView2 Runtime (pre-installed on Windows 10+), `rustup default stable-msvc`

**Linux (Debian/Ubuntu):**
```bash
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
```

**Mobile (optional):** See `references/mobile.md` for Android Studio / iOS setup.

## Creating a Project

### Scaffolding (recommended)

```bash
npm create tauri-app@latest
# Choose: TypeScript/JavaScript → pnpm/npm → React → TypeScript
cd my-app
npm install
npm run tauri dev
```

This creates a project with `src/` (React frontend) and `src-tauri/` (Rust backend).

### Adding Tauri to an existing project

```bash
npm install -D @tauri-apps/cli@latest
npx tauri init
```

Answer the prompts for app name, dev server URL (e.g. `http://localhost:5173` for Vite), and frontend dist directory (e.g. `../dist`).

## Core Concepts

### Commands — Frontend calls Rust

Commands are the primary way the frontend talks to the backend. Define a Rust function with `#[tauri::command]`, register it, and call it from JS with `invoke`.

**Rust side** (`src-tauri/src/lib.rs`):
```rust
#[tauri::command]
fn greet(name: String) -> String {
    format!("Hello, {}!", name)
}

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![greet])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

**JS side**:
```typescript
import { invoke } from '@tauri-apps/api/core';

const greeting = await invoke<string>('greet', { name: 'World' });
```

Key rules:
- Command names must be unique across the app
- Rust args are snake_case, JS passes them as camelCase (e.g. `invoke_message` → `{ invokeMessage: '...' }`)
- Use `#[tauri::command(rename_all = "snake_case")]` to keep snake_case on both sides
- Commands can be `async` for non-blocking work
- Return `Result<T, String>` (or custom error types) for error handling — `Err` rejects the JS promise

### Events — Rust notifies the frontend

For fire-and-forget notifications or streaming updates, use the event system:

**Rust emitting:**
```rust
use tauri::{AppHandle, Emitter};

#[tauri::command]
fn start_download(app: AppHandle, url: String) {
    app.emit("download-progress", 50).unwrap();
}
```

**JS listening:**
```typescript
import { listen } from '@tauri-apps/api/event';

const unlisten = await listen<number>('download-progress', (event) => {
    console.log(`Progress: ${event.payload}%`);
});
// Call unlisten() to stop listening
```

### Channels — High-throughput streaming

For ordered, high-throughput data (file reads, progress), use channels instead of events:

```rust
use tauri::ipc::Channel;

#[tauri::command]
async fn stream_data(on_chunk: Channel<Vec<u8>>) {
    for chunk in data_chunks {
        on_chunk.send(chunk).unwrap();
    }
}
```

```typescript
import { invoke, Channel } from '@tauri-apps/api/core';

const onChunk = new Channel<Uint8Array>();
onChunk.onmessage = (chunk) => { /* handle chunk */ };
await invoke('stream_data', { onChunk });
```

### State Management

Register state with `.manage()` and inject it into commands with `State<>`:

```rust
use std::sync::Mutex;
use tauri::State;

struct AppState {
    count: u32,
}

#[tauri::command]
fn increment(state: State<'_, Mutex<AppState>>) -> u32 {
    let mut s = state.lock().unwrap();
    s.count += 1;
    s.count
}

// In run():
tauri::Builder::default()
    .manage(Mutex::new(AppState { count: 0 }))
    .invoke_handler(tauri::generate_handler![increment])
```

Important: Tauri wraps state in `Arc` automatically — don't wrap in `Arc` yourself. Use `Mutex` for mutable state. Use `std::sync::Mutex` (not tokio's) unless you need to hold the lock across `.await` points.

**Type mismatch pitfall:** If you `.manage(Mutex::new(state))` but inject `State<'_, AppState>` (without `Mutex`), it panics at runtime, not compile time. Use a type alias to prevent this:
```rust
type AppState = Mutex<AppStateInner>;
```

## Configuration — tauri.conf.json

The config file lives at `src-tauri/tauri.conf.json`. Key sections:

```jsonc
{
  "productName": "My App",
  "version": "1.0.0",
  "identifier": "com.example.myapp",  // Required, reverse domain notation
  "build": {
    "devUrl": "http://localhost:5173",      // Dev server URL
    "frontendDist": "../dist",              // Production build output
    "beforeDevCommand": "npm run dev",      // Starts your dev server
    "beforeBuildCommand": "npm run build"   // Builds frontend for production
  },
  "app": {
    "windows": [{
      "title": "My App",
      "width": 1024,
      "height": 768
    }],
    "security": {
      "capabilities": []  // Reference capability files here
    }
  },
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": ["icons/32x32.png", "icons/128x128.png", "icons/icon.icns", "icons/icon.ico"]
  }
}
```

Platform-specific overrides: `tauri.linux.conf.json`, `tauri.windows.conf.json`, `tauri.macos.conf.json` — these merge with the main config.

See `references/config.md` for the full configuration reference.

## Security — Permissions & Capabilities

Tauri v2 has a capability-based security model. By default, the frontend cannot call any commands — you must explicitly grant access.

### Capabilities

A capability grants a set of permissions to specific windows. Create JSON files in `src-tauri/capabilities/`:

```json
{
  "identifier": "main-capability",
  "description": "Permissions for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "my-app:default"
  ]
}
```

### Permissions for your own commands

Define in `src-tauri/permissions/default.toml`:

```toml
[default]
description = "Default permissions for the app"
permissions = ["allow-greet", "allow-increment"]
```

Each command you register automatically gets `allow-<command-name>` and `deny-<command-name>` identifiers.

### Plugin permissions

Plugins ship their own permissions. Add them to your capability:

```json
{
  "permissions": [
    "core:default",
    "fs:default",
    "fs:allow-read-file",
    "dialog:default",
    "shell:allow-open"
  ]
}
```

### Scoped permissions

Restrict commands to specific paths/resources:

```toml
[[permission]]
identifier = "scope-home"
description = "Access files in $HOME"

[[scope.allow]]
path = "$HOME/*"
```

See `references/permissions.md` for the full permissions reference.

## Plugins

Install official plugins via npm + cargo:

```bash
npm install @tauri-apps/plugin-fs
# The Cargo dependency is added automatically by the CLI
```

Register in Rust:
```rust
tauri::Builder::default()
    .plugin(tauri_plugin_fs::init())
```

Use in JS:
```typescript
import {