# 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 Developer Guide (2 parts) ──────────────────────
│   ├── 01-core-architecture-config-commands-ipc.md     # Sections 1–7
│   ├── 02-windows-plugins-websocket-state-migration.md  # Sections 8–15
│   │
│   │  ── Agent Prompts (2 parts) ──────────────────────────────────
│   ├── 01-system-prompt-and-common-prompts.md          # System prompt + prompts 1–7
│   ├── 02-advanced-prompts-checklist-migration.md     # Prompts 8–15 + checklist + API map
│   │
│   │  ── Error Resolution Guide (2 parts) ────────────────────────
│   ├── 01-build-config-permission-plugin-errors.md     # Categories A–H
│   └── 02-runtime-platform-mobile-errors.md             # Categories I–R + Top 25
│
├── tauri2-docs/                                     # SUPPLEMENTARY REFERENCES
│   ├── cheatsheet.md                                  # Quick-reference cheat sheet
│   ├── ws_server_client_inject_guide.md               # WebSocket server, client, injection deep-dive
│   └── tauri2-links.md                                # Curated links to official docs
│
└── README.md                                        # THIS FILE — navigation index
```

All guide files are sized under **8k tokens** so small LLMs can load them without losing context. Each split file includes cross-reference links to its companion part.

---

## 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 file, 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 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** Part 1 as your primary reference for core concepts. Part 2 covers advanced topics. 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

### Definitive Developer Guide

| Topic | File | Sections |
|-------|------|----------|
| Architecture overview, project structure, scaffolding | `01-core-architecture-config-commands-ipc.md` | 1–2 |
| Configuration (`tauri.conf.json` v2 schema) | `01-core-architecture-config-commands-ipc.md` | 3 |
| Capabilities & permissions (ACL security model) | `01-core-architecture-config-commands-ipc.md` | 4 |
| Rust backend: `lib.rs`, commands, Builder pattern | `01-core-architecture-config-commands-ipc.md` | 5 |
| Frontend integration (JS imports, invoke, plugins) | `01-core-architecture-config-commands-ipc.md` | 6 |
| IPC: commands, events, channels, streaming | `01-core-architecture-config-commands-ipc.md` | 7 |
| Window management (multi-window, external URLs) | `02-windows-plugins-websocket-state-migration.md` | 8 |
| Plugin ecosystem (all 33+ official plugins) | `02-windows-plugins-websocket-state-migration.md` | 9 |
| Native WebSocket server (Tokio + broadcast) | `02-windows-plugins-websocket-state-migration.md` / `tauri2-docs/ws_server_client_inject_guide.md` | 10 |
| Script injection into webview windows | `02-windows-plugins-websocket-state-migration.md` / `tauri2-docs/ws_server_client_inject_guide.md` | 11 |
| State management (Mutex, managed state) | `02-windows-plugins-websocket-state-migration.md` | 12 |
| v1 to v2 migration (full API diff) | `02-windows-plugins-websocket-state-migration.md` | 13 |
| Anti-patterns to avoid | `02-windows-plugins-websocket-state-migration.md` | 14 |
| Quick reference cheat sheet | `02-windows-plugins-websocket-state-migration.md` | 15 |

### Agent Prompts

| Topic | File | Section |
|-------|------|---------|
| Universal system prompt (REQUIRED prefix) | `01-system-prompt-and-common-prompts.md` | 1 |
| Scaffold a new Tauri 2.0 project | `01-system-prompt-and-common-prompts.md` | 2 |
| Add a Tauri plugin | `01-system-prompt-and-common-prompts.md` | 3 |
| Create a custom command (IPC) | `01-system-prompt-and-common-prompts.md` | 4 |
| Add state management | `01-system-prompt-and-common-prompts.md` | 5 |
| Implement event-based communication | `01-system-prompt-and-common-prompts.md` | 6 |
| Create multi-window app | `01-system-prompt-and-common-prompts.md` | 7 |
| Build a WebSocket server in Rust | `02-advanced-prompts-checklist-migration.md` | 8 |
| Implement script injection | `02-advanced-prompts-checklist-migration.md` | 9 |
| Set up capabilities & permissions | `02-advanced-prompts-checklist-migration.md` | 10 |
| Migrate a v1 app to v2 | `02-advanced-prompts-checklist-migration.md` | 11 |
| Full app build (end-to-end) | `02-advanced-prompts-checklist-migration.md` | 12 |
| Verification checklist for agents | `02-advanced-prompts-checklist-migration.md` | 13 |
| v1 vs v2 API map | `02-advanced-prompts-checklist-migration.md` | 14 |
| Debug a Tauri 2.0 build/compile error | `02-advanced-prompts-checklist-migration.md` | 15 |

### Error Resolution Guide

| Topic | File | Category |
|-------|------|----------|
| Rust compilation errors (Cargo build failures) | `01-build-config-permission-plugin-errors.md` | A |
| v1-to-v2 migration compile errors | `01-build-config-permission-plugin-errors.md` | B |
| Async/thread safety errors (Mutex, Send, lifetime) | `01-build-config-permission-plugin-errors.md` | C |
| Config errors (`tauri.conf.json` validation) | `01-build-config-permission-plugin-errors.md` | D |
| Permission/capability errors ("not allowed") | `01-build-config-permission-plugin-errors.md` | E |
| Plugin integration errors | `01-build-config-permission-plugin-errors.md` | F |
| IPC / command runtime errors | `01-build-config-permission-plugin-errors.md` | G |
| Webview & window runtime errors | `01-build-config-permission-plugin-errors.md` | H |
| Event system errors | `02-runtime-platform-mobile-errors.md` | I |
| Content Security Policy (CSP) errors | `02-runtime-platform-mobile-errors.md` | J |
| Frontend integration errors (Vite, Next.js, SvelteKit) | `02-runtime-platform-mobile-errors.md` | K |
| WebSocket errors | `02-runtime-platform-mobile-errors.md` | L |
| Path & asset protocol errors | `02-runtime-platform-mobile-errors.md` | M |
| Shell & sidecar errors | `02-runtime-platform-mobile-errors.md` | N |
| Mobile build errors (iOS & Android) | `02-runtime-platform-mobile-errors.md` | O |
| Platform-specific build errors | `02-runtime-platform-mobile-errors.md` | P |
| Panics & runtime crashes | `02-runtime-platform-mobile-errors.md` | Q |
| Error handling best practices | `02-runtime-platform-mobile-errors.md` | R |
| Top 25 most common errors (quick lookup) | `02-runtime-platform-mobile-errors.md` | Quick-Reference |

### Supplementary References

| Topic | File |
|-------|------|
| Quick-reference cheat sheet (commands, config, IPC, WebSocket patterns) | `tauri2-docs/cheatsheet.md` |
| WebSocket server + client + injection deep-dive | `tauri2-docs/ws_server_client_inject_guide.md` |
| Links to official docs (migration, security, config) | `tauri2-docs/tauri2-links.md` |

---

## 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 `02-advanced-prompts-checklist-migration.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 the Error Resolution Guide files
- **API names**: Search for type names (e.g., `WebviewWindowBuilder`, `Emitter`, `Channel`) in the Definitive Guide files
- **Config keys**: Search for JSON key names (e.g., `frontendDist`, `withGlobalTauri`, `capabilities`) in `01-core-architecture-config-commands-ipc.md`
- **Plugin names**: Search for plugin identifiers (e.g., `tauri-plugin-fs`, `plugin-dialog`, `store:default`) in `02-windows-plugins-websocket-state-migration.md`
- **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 the Definitive Guide 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 `01-core-architecture-config-commands-ipc.md` Section 4 and `01-build-config-permission-plugin-errors.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/ |