tauri2-guide/README.md

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

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

#[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])

// 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/