From 75f2a307226b45ae71c4a7c774a361a67e24dc0b Mon Sep 17 00:00:00 2001 From: Z User Date: Sat, 30 May 2026 20:34:25 +0000 Subject: [PATCH] Rewrite README as LLM-navigable reference index --- README.md | 186 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 185 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5080b83..b8b3c26 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,186 @@ -# tauri2-vin-ws-temp +# 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/` | `@tauri-apps/plugin-` | +| 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- = "2"` to `src-tauri/Cargo.toml` +2. **Registration** — Add `.plugin(tauri_plugin_::init())` in the `tauri::Builder` +3. **JS package** — `npm install @tauri-apps/plugin-` +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/.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 { + 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/ |