368a3db23d
- definitive-guide.md → 2 parts (core/arch/config/commands + windows/plugins/websocket/state/migration) - error-resolution-guide.md → 2 parts (build/config/plugin errors + runtime/platform/mobile errors) - agent-prompts.md → 2 parts (system prompt/common tasks + advanced tasks/checklist/migration map) - Updated README.md with new file structure and per-topic routing table - All files under ~7.5k tokens, suitable for 8k context windows - Cross-reference links between split parts
228 lines
13 KiB
Markdown
228 lines
13 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 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/ |
|