Tauri
Overview
Tauri is a framework for building desktop and mobile applications using web technologies (HTML, CSS, JavaScript/TypeScript) for the UI and Rust for the backend logic. It produces small, fast binaries by leveraging the OS webview instead of bundling a browser engine. The IPC layer connects the frontend to Rust commands through a capability-based permission system.
When to use: Cross-platform desktop/mobile apps with web UIs, system-level integrations (tray, notifications, file system), apps requiring small bundle sizes, security-sensitive applications needing fine-grained permission control.
When NOT to use: Pure web apps with no native requirements, Electron apps that depend heavily on Node.js APIs with no Rust migration path, projects where the team has no capacity to maintain Rust code.
Quick Reference
| Pattern |
API / Config |
Key Points |
| Create project |
cargo create-tauri-app or pnpm create tauri-app |
Scaffolds Rust backend + frontend framework |
| Define command |
#[tauri::command] fn name() {} |
Must register in generate_handler! |
| Invoke from frontend |
invoke('cmd_name', { arg: value }) |
Returns Promise, args as camelCase JSON |
| Emit event (frontend) |
emit('event-name', payload) |
Global event, all listeners receive |
| Listen event |
listen('event-name', handler) |
Returns unlisten function |
| Manage state |
app.manage(MyState {}) + State<'_, MyState> |
No Arc needed, Mutex for mutability |
| Window creation |
WebviewWindowBuilder::new(app, label, url) |
Label must be unique per window |
| System tray |
TrayIconBuilder::new().menu(&menu).build(app) |
Requires tray-icon Cargo feature |
| Add plugin (Rust) |
.plugin(tauri_plugin_name::init()) |
Register in Builder chain |
| Add plugin (frontend) |
@tauri-apps/plugin-name |
NPM package per plugin |
| Define capability |
src-tauri/capabilities/*.json |
Scoped to windows, merged at build |
| Grant permission |
"permissions": ["plugin:scope"] |
Commands inaccessible without explicit grant |
| Sidecar binary |
tauri.conf.json bundle.externalBin |
Name must match {name}-{target_triple} |
| Custom protocol |
tauri::Builder::default().register_uri_scheme_protocol |
Intercept custom scheme:// URLs |
| Auto-updater |
tauri-plugin-updater + JSON endpoint |
Requires code signing |
| App bundle/sign |
cargo tauri build |
Platform-specific signing via env vars |
Common Mistakes
| Mistake |
Correct Pattern |
Multiple generate_handler! calls |
Pass all commands to a single generate_handler! invocation |
Using &str in async command args |
Use owned String types in async commands |
| Forgetting to add capability for plugin |
Add permission identifier in src-tauri/capabilities/*.json |
Wrapping state in Arc |
Tauri State handles reference counting internally |
Using std::sync::Mutex across .await points |
Use tokio::sync::Mutex for async commands holding locks across awaits |
| Wrong sidecar binary name |
Binary must be named {name}-{target_triple} (e.g., mybin-x86_64-pc-windows-msvc) |
| Assuming all windows share capabilities |
Each window/webview gets capabilities scoped by label |
Using SystemTray (v1 API) |
Use TrayIconBuilder from tauri::tray module in v2 |
| Not signing app before enabling updater |
Auto-updater requires valid code signing on all platforms |
| Using window title for security decisions |
Capabilities use window labels, not titles |
Delegation
- Command pattern discovery: Use
Explore agent
- Security review: Use
Task agent
- Code review: Delegate to
code-reviewer agent
If the rust skill is available, delegate Rust language patterns, error handling, and async/concurrency to it.
If the react-patterns skill is available, delegate React frontend patterns to it.
If the svelte skill is available, delegate Svelte frontend patterns to it.
If the vite skill is available, delegate build tooling and dev server configuration to it.
If the github-actions skill is available, delegate CI/CD pipeline and release workflow configuration to it.
References
- Project setup, configuration, and directory structure
- IPC commands, events, and channels
- State management patterns
- Window management and multi-window apps
- System tray and menus
- Plugin system and official plugins
- Security model, capabilities, and permissions
- Sidecar binaries and custom protocols
- App signing, distribution, and auto-updates
1---2name: tauri3description: Tauri v2 framework for building desktop and mobile applications with web frontends and Rust backends. Covers project setup, IPC commands and events, window management, system tray, file system access, plugin system (clipboard, dialog, notification, updater, deep-link), multi-window apps, sidecar binaries, custom protocols, app signing, distribution, auto-updates, and the capability-based security model. Use when scaffolding a Tauri project, defining Rust commands, invoking backend logic from the frontend, configuring permissions and capabilities, setting up plugins, managing application state, building system tray menus, creating multi-window layouts, bundling sidecar binaries, implementing auto-updates, or signing apps for distribution.4license: MIT5---6
7# Tauri
8
9## Overview
10
11Tauri is a framework for building **desktop and mobile applications** using web technologies (HTML, CSS, JavaScript/TypeScript) for the UI and **Rust** for the backend logic. It produces small, fast binaries by leveraging the OS webview instead of bundling a browser engine. The IPC layer connects the frontend to Rust commands through a capability-based permission system.
12
13**When to use:** Cross-platform desktop/mobile apps with web UIs, system-level integrations (tray, notifications, file system), apps requiring small bundle sizes, security-sensitive applications needing fine-grained permission control.
14
15**When NOT to use:** Pure web apps with no native requirements, Electron apps that depend heavily on Node.js APIs with no Rust migration path, projects where the team has no capacity to maintain Rust code.
16
17## Quick Reference
18
19| Pattern | API / Config | Key Points |
20| --------------------- | -------------------------------------------------------- | -------------------------------------------- |
21| Create project | `cargo create-tauri-app` or `pnpm create tauri-app` | Scaffolds Rust backend + frontend framework |
22| Define command | `#[tauri::command] fn name() {}` | Must register in `generate_handler!` |
23| Invoke from frontend | `invoke('cmd_name', { arg: value })` | Returns Promise, args as camelCase JSON |
24| Emit event (frontend) | `emit('event-name', payload)` | Global event, all listeners receive |
25| Listen event | `listen('event-name', handler)` | Returns unlisten function |
26| Manage state | `app.manage(MyState {})` + `State<'_, MyState>` | No Arc needed, Mutex for mutability |
27| Window creation | `WebviewWindowBuilder::new(app, label, url)` | Label must be unique per window |
28| System tray | `TrayIconBuilder::new().menu(&menu).build(app)` | Requires `tray-icon` Cargo feature |
29| Add plugin (Rust) | `.plugin(tauri_plugin_name::init())` | Register in `Builder` chain |
30| Add plugin (frontend) | `@tauri-apps/plugin-name` | NPM package per plugin |
31| Define capability | `src-tauri/capabilities/*.json` | Scoped to windows, merged at build |
32| Grant permission | `"permissions": ["plugin:scope"]` | Commands inaccessible without explicit grant |
33| Sidecar binary | `tauri.conf.json` `bundle.externalBin` | Name must match `{name}-{target_triple}` |
34| Custom protocol | `tauri::Builder::default().register_uri_scheme_protocol` | Intercept custom `scheme://` URLs |
35| Auto-updater | `tauri-plugin-updater` + JSON endpoint | Requires code signing |
36| App bundle/sign | `cargo tauri build` | Platform-specific signing via env vars |
37
38## Common Mistakes
39
40| Mistake | Correct Pattern |
41| ----------------------------------------------- | ------------------------------------------------------------------------------------ |
42| Multiple `generate_handler!` calls | Pass all commands to a single `generate_handler!` invocation |
43| Using `&str` in async command args | Use owned `String` types in async commands |
44| Forgetting to add capability for plugin | Add permission identifier in `src-tauri/capabilities/*.json` |
45| Wrapping state in `Arc` | Tauri `State` handles reference counting internally |
46| Using `std::sync::Mutex` across `.await` points | Use `tokio::sync::Mutex` for async commands holding locks across awaits |
47| Wrong sidecar binary name | Binary must be named `{name}-{target_triple}` (e.g., `mybin-x86_64-pc-windows-msvc`) |
48| Assuming all windows share capabilities | Each window/webview gets capabilities scoped by label |
49| Using `SystemTray` (v1 API) | Use `TrayIconBuilder` from `tauri::tray` module in v2 |
50| Not signing app before enabling updater | Auto-updater requires valid code signing on all platforms |
51| Using window title for security decisions | Capabilities use window **labels**, not titles |
52
53## Delegation
54
55- **Command pattern discovery**: Use `Explore` agent
56- **Security review**: Use `Task` agent
57- **Code review**: Delegate to `code-reviewer` agent
58
59> If the `rust` skill is available, delegate Rust language patterns, error handling, and async/concurrency to it.
60> If the `react-patterns` skill is available, delegate React frontend patterns to it.
61> If the `svelte` skill is available, delegate Svelte frontend patterns to it.
62> If the `vite` skill is available, delegate build tooling and dev server configuration to it.
63> If the `github-actions` skill is available, delegate CI/CD pipeline and release workflow configuration to it.
64
65## References
66
67- [Project setup, configuration, and directory structure](references/project-setup.md)
68- [IPC commands, events, and channels](references/ipc-commands.md)
69- [State management patterns](references/state-management.md)
70- [Window management and multi-window apps](references/window-management.md)
71- [System tray and menus](references/system-tray.md)
72- [Plugin system and official plugins](references/plugin-system.md)
73- [Security model, capabilities, and permissions](references/security-model.md)
74- [Sidecar binaries and custom protocols](references/sidecar-protocols.md)
75- [App signing, distribution, and auto-updates](references/distribution.md)
oakoss