187 lines
11 KiB
Markdown
187 lines
11 KiB
Markdown
# 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/ |
|