# Tauri 2.0 Developer Reference Library

A comprehensive, self-contained reference library for building applications with **Tauri 2.0** (Rust backend + web frontend). All code examples are validated against the Tauri 2.0 API. This repository contains guides, agent prompts, error resolution references, and cheat sheets — designed to be searched and referenced directly by LLMs and developers.

**Official Tauri 2.0 Documentation**: https://v2.tauri.app
**Rust API Docs**: https://docs.rs/tauri/latest/tauri/

---

## Repository Structure

```text
tauri2-vin-ws-temp/
├── tauri2-guide/                              # AUTHORITATIVE GUIDES — start here
│   ├── definitive-guide.md                   # Full reference (architecture, config, commands, events, plugins, windows, state, migration)
│   ├── agent-prompts.md                      # Copy-paste prompts for instructing LLM agents to build Tauri 2.0 apps
│   └── error-resolution-guide.md             # Every known error category with exact messages, root causes, and solutions
│
├── tauri2-docs/                               # SUPPLEMENTARY REFERENCES
│   ├── cheatsheet.md                          # Quick-reference cheat sheet (commands, config, IPC, WebSocket patterns)
│   ├── ws_server_client_inject_guide.md       # Deep-dive: native WebSocket server, frontend clients, script injection
│   └── tauri2-links.md                        # Curated links to official Tauri 2.0 documentation pages
│
└── README.md                                  # THIS FILE — navigation index for LLMs and developers
```

---

## How to Use This Repository

### For LLMs / AI Agents

This repository is designed to be **searched directly**. When you receive a Tauri 2.0 question, use the table below to locate the most relevant document, then read the specific section referenced.

**Important constraints for agents:**
- You **cannot compile or run code** in a sandbox. Verify correctness using logic, API pattern matching, and cross-referencing these documents.
- All code in this repository is **Tauri 2.0 only** — do NOT use v1 patterns (see the migration section in `definitive-guide.md` for the full v1-to-v2 diff).
- Every plugin requires 4 things: (1) Rust crate in `Cargo.toml`, (2) `.plugin()` registration in the Builder, (3) npm package, (4) permissions in capabilities.

### For Developers

Use the **Definitive Guide** (`tauri2-guide/definitive-guide.md`) as your primary reference. It covers every aspect of Tauri 2.0 development end-to-end. For specific tasks, use the **Agent Prompts** as templates. For debugging, search the **Error Resolution Guide** by error message.

---

## Document Index — What to Read for Each Topic

| Topic | File | Key Sections |
|-------|------|-------------|
| **Architecture overview, project structure, scaffolding** | `tauri2-guide/definitive-guide.md` | Sections 1–2 |
| **Configuration (`tauri.conf.json` v2 schema)** | `tauri2-guide/definitive-guide.md` | Section 3 |
| **Capabilities & permissions (ACL security model)** | `tauri2-guide/definitive-guide.md` | Section 4 |
| **Rust backend: `lib.rs`, commands, `Builder` pattern** | `tauri2-guide/definitive-guide.md` | Section 5 |
| **Frontend integration (JS imports, `invoke`, plugins)** | `tauri2-guide/definitive-guide.md` | Section 6 |
| **IPC: commands, events, channels, streaming** | `tauri2-guide/definitive-guide.md` | Section 7 |
| **Window management (multi-window, external URLs)** | `tauri2-guide/definitive-guide.md` | Section 8 |
| **Plugin ecosystem (all 33+ official plugins)** | `tauri2-guide/definitive-guide.md` | Section 9 |
| **Native WebSocket server (Tokio + broadcast)** | `tauri2-guide/definitive-guide.md` Section 10 / `tauri2-docs/ws_server_client_inject_guide.md` Part 1 |
| **Script injection into webview windows** | `tauri2-guide/definitive-guide.md` Section 11 / `tauri2-docs/ws_server_client_inject_guide.md` Part 3 |
| **State management (Mutex, managed state)** | `tauri2-guide/definitive-guide.md` | Section 12 |
| **v1 to v2 migration (full API diff)** | `tauri2-guide/definitive-guide.md` Section 13 / `tauri2-guide/agent-prompts.md` Section 14 |
| **Anti-patterns to avoid** | `tauri2-guide/definitive-guide.md` | Section 14 |
| **Quick reference cheat sheet** | `tauri2-docs/cheatsheet.md` | All sections |
| **WebSocket server + client + injection deep-dive** | `tauri2-docs/ws_server_client_inject_guide.md` | Parts 1–3 |
| **Links to official docs (migration, security, config)** | `tauri2-docs/tauri2-links.md` | All entries |
| **Agent system prompt (mandatory prefix for all tasks)** | `tauri2-guide/agent-prompts.md` | Section 1 |
| **Task-specific agent prompts (scaffold, plugin, command, etc.)** | `tauri2-guide/agent-prompts.md` | Sections 2–12 |
| **Agent verification checklist** | `tauri2-guide/agent-prompts.md` | Section 13 |
| **Rust compilation errors (Cargo build failures)** | `tauri2-guide/error-resolution-guide.md` | Category A |
| **v1-to-v2 migration compile errors** | `tauri2-guide/error-resolution-guide.md` | Category B |
| **Async/thread safety errors (Mutex, Send, lifetime)** | `tauri2-guide/error-resolution-guide.md` | Category C |
| **Config errors (`tauri.conf.json` validation)** | `tauri2-guide/error-resolution-guide.md` | Category D |
| **Permission/capability errors ("not allowed")** | `tauri2-guide/error-resolution-guide.md` | Category E |
| **Plugin integration errors** | `tauri2-guide/error-resolution-guide.md` | Category F |
| **IPC / command runtime errors** | `tauri2-guide/error-resolution-guide.md` | Category G |
| **Webview & window runtime errors** | `tauri2-guide/error-resolution-guide.md` | Category H |
| **Event system errors** | `tauri2-guide/error-resolution-guide.md` | Category I |
| **Content Security Policy (CSP) errors** | `tauri2-guide/error-resolution-guide.md` | Category J |
| **Frontend integration errors (Vite, Next.js, SvelteKit)** | `tauri2-guide/error-resolution-guide.md` | Category K |
| **WebSocket errors** | `tauri2-guide/error-resolution-guide.md` | Category L |
| **Path & asset protocol errors** | `tauri2-guide/error-resolution-guide.md` | Category M |
| **Shell & sidecar errors** | `tauri2-guide/error-resolution-guide.md` | Category N |
| **Mobile build errors (iOS & Android)** | `tauri2-guide/error-resolution-guide.md` | Category O |
| **Platform-specific build errors** | `tauri2-guide/error-resolution-guide.md` | Category P |
| **Panics & runtime crashes** | `tauri2-guide/error-resolution-guide.md` | Category Q |
| **Error handling best practices** | `tauri2-guide/error-resolution-guide.md` | Category R |
| **Top 25 most common errors (quick lookup)** | `tauri2-guide/error-resolution-guide.md` | Quick-Reference section |

---

## Key Tauri 2.0 Concepts (Quick Orientation)

### The v1 vs v2 Difference — Critical

Tauri 2.0 is a **complete rewrite**, not an incremental update. The most common mistake is using v1 API patterns in a v2 project. The most frequently violated rules:

| Area | v1 (WRONG in v2) | v2 (Correct) |
|------|-------------------|---------------|
| Window type | `tauri::Window` | `tauri::WebviewWindow` |
| Window builder | `tauri::WindowBuilder` | `tauri::WebviewWindowBuilder` |
| Window URL | `tauri::WindowUrl` | `tauri::WebviewUrl` |
| Get window | `get_window("main")` | `get_webview_window("main")` |
| JS invoke import | `@tauri-apps/api/tauri` | `@tauri-apps/api/core` |
| JS window import | `@tauri-apps/api/window` | `@tauri-apps/api/webviewWindow` |
| Plugin JS imports | `@tauri-apps/api/<name>` | `@tauri-apps/plugin-<name>` |
| Config app section | `tauri` key | `app` key |
| Config dist dir | `build.distDir` | `build.frontendDist` |
| Security model | `allowlist` in config | Capabilities + Permissions (ACL) |
| Core logic file | `main.rs` only | `lib.rs` + `main.rs` pattern |
| Event emit | `window.emit()` | `app.emit()` (global) / `app.emit_to()` (targeted) |
| Rust APIs | `tauri::api::*` modules | Everything moved to plugins |

**Full migration map**: See `tauri2-guide/agent-prompts.md` Section 14 (v1 vs v2 API Map).

### The 4-Step Plugin Pattern

Every Tauri 2.0 plugin requires all four steps:

1. **Rust crate** — Add `tauri-plugin-<name> = "2"` to `src-tauri/Cargo.toml`
2. **Registration** — Add `.plugin(tauri_plugin_<name>::init())` in the `tauri::Builder`
3. **JS package** — `npm install @tauri-apps/plugin-<name>`
4. **Permissions** — Add permission identifiers (e.g., `fs:default`) to `src-tauri/capabilities/default.json`

### The Project Structure Pattern

```
src/                      → Frontend UI (HTML/CSS/JS or any framework)
src-tauri/                → Rust backend
  src/main.rs            → Minimal desktop entry-point (calls lib::run())
  src/lib.rs             → Core app logic, Builder, commands, setup
  src/<modules>.rs        → Additional Rust modules
  capabilities/           → Security capability JSON files
  tauri.conf.json         → Main config (v2 schema)
  Cargo.toml              → Rust dependencies
  build.rs                → Tauri build script
```

### The Command Pattern

```rust
#[tauri::command]
async fn my_command(name: String) -> Result<String, String> {
    Ok(format!("Hello, {}!", name))
}

// Register in Builder (single invoke_handler call only):
.invoke_handler(tauri::generate_handler![my_command])
```

```javascript
// Frontend invocation
import { invoke } from '@tauri-apps/api/core';
const result = await invoke('my_command', { name: 'World' });
```

---

## Search Tips for LLMs

When looking for information in this repository, search for these keywords and patterns:

- **Error messages**: Search the exact error string (e.g., `"unresolved import tauri::api"`, `"command not found"`, `"not allowed"`) in `error-resolution-guide.md`
- **API names**: Search for type names (e.g., `WebviewWindowBuilder`, `Emitter`, `Channel`) in `definitive-guide.md`
- **Config keys**: Search for JSON key names (e.g., `frontendDist`, `withGlobalTauri`, `capabilities`) in `definitive-guide.md` Section 3
- **Plugin names**: Search for plugin identifiers (e.g., `tauri-plugin-fs`, `plugin-dialog`, `store:default`) in `definitive-guide.md` Section 9
- **Migration**: Search for old v1 names (e.g., `WindowBuilder`, `allowlist`, `@tauri-apps/api/tauri`) to find their v2 replacements
- **Patterns**: Search for pattern keywords (e.g., `initialization_script`, `run_on_main_thread`, `broadcast channel`, `include_str`) in both `definitive-guide.md` and `ws_server_client_inject_guide.md`
- **Permission identifiers**: Search for permission strings (e.g., `core:event:allow-listen`, `fs:allow-read`, `http:default`) in `definitive-guide.md` Section 4 and `error-resolution-guide.md` Category E

---

## Official External References

These links point to the canonical Tauri 2.0 documentation. Always prefer these for the latest API details:

| Resource | URL |
|----------|-----|
| Main documentation hub | https://v2.tauri.app |
| Migration from v1 to v2 | https://v2.tauri.app/start/migrate/from-tauri-1/ |
| Capabilities & security model | https://v2.tauri.app/security/capabilities/ |
| Permissions reference | https://v2.tauri.app/security/permissions/ |
| Configuration files schema | https://v2.tauri.app/develop/configuration-files/ |
| Calling Rust from frontend | https://v2.tauri.app/develop/calling-rust/ |
| Calling frontend from Rust | https://v2.tauri.app/develop/calling-frontend/ |
| Plugin index | https://v2.tauri.app/plugin/ |
| Rust crate API docs | https://docs.rs/tauri/latest/tauri/ |