/tauri-v2

Tauri v2+ Advanced Runtime Reference

Contents

• System Tray (TrayIconBuilder)
• Sidecars (External Binaries)
• Deep Links (tauri-plugin-deep-link)
• Custom Protocols

Covers system tray integration, sidecar processes, deep links, and custom protocols. Last verified: 2026-04-02. Check official Tauri v2+ docs for updates.

See also:

• plugin-reference.md — plugin installation and permissions
• capabilities-reference.md — capability/permission model

Section 1: System Tray (TrayIconBuilder)

v2 Change: SystemTray from v1 is replaced by TrayIconBuilder in v2. Do NOT use SystemTray.

// In lib.rs run() function, in setup hook:
use tauri::{
    tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent},
    Manager,
};

tauri::Builder::default()
    .setup(|app| {
        let tray = TrayIconBuilder::new()
            .icon(app.default_window_icon().unwrap().clone())
            .tooltip("My App")
            .on_tray_icon_event(|tray, event| {
                if let TrayIconEvent::Click {
                    button: MouseButton::Left,
                    button_state: MouseButtonState::Up,
                    ..
                } = event
                {
                    let app = tray.app_handle();
                    if let Some(window) = app.get_webview_window("main") {
                        let _ = window.show();
                        let _ = window.set_focus();
                    }
                }
            })
            .build(app)?;
        Ok(())
    })

Show tray menu example:

use tauri::menu::{Menu, MenuItem};

let quit_item = MenuItem::with_id(app, "quit", "Quit", true, None::<&str>)?;
let menu = Menu::with_items(app, &[&quit_item])?;
let tray = TrayIconBuilder::new()
    .icon(app.default_window_icon().unwrap().clone())
    .menu(&menu)
    .on_menu_event(|app, event| match event.id.as_ref() {
        "quit" => app.exit(0),
        _ => {}
    })
    .build(app)?;

Platform notes:

• macOS: tray icon appears in menu bar; supports template images
• Windows: tray icon in system tray; click events differ from macOS
• Linux: tray support varies by desktop environment (requires libappindicator or libayatana-appindicator)

Section 2: Sidecars (External Binaries)

Show config and usage for bundled executables:

// tauri.conf.json
{
  "bundle": {
    "externalBin": [
      "binaries/my-sidecar"
    ]
  }
}

Capability permission required:

{
  "permissions": [
    {
      "identifier": "shell:allow-execute",
      "allow": [
        { "name": "my-sidecar", "args": true, "sidecar": true }
      ]
    }
  ]
}

Rust code to execute sidecar:

use tauri_plugin_shell::ShellExt;

#[tauri::command]
async fn run_sidecar(app: tauri::AppHandle) -> Result<String, String> {
    let output = app.shell()
        .sidecar("my-sidecar")
        .map_err(|e| e.to_string())?
        .args(["--flag", "value"])
        .output()
        .await
        .map_err(|e| e.to_string())?;
    
    Ok(String::from_utf8_lossy(&output.stdout).to_string())
}

Binary naming convention (for cross-platform bundling):

• macOS (Intel): my-sidecar-x86_64-apple-darwin
• macOS (ARM): my-sidecar-aarch64-apple-darwin
• Windows: my-sidecar-x86_64-pc-windows-msvc.exe
• Linux: my-sidecar-x86_64-unknown-linux-gnu

Section 3: Deep Links (tauri-plugin-deep-link)

cargo tauri add deep-link

Config in tauri.conf.json:

{
  "plugins": {
    "deep-link": {
      "mobile": [
        { "scheme": "myapp" }
      ],
      "desktop": [
        { "schemes": ["myapp"] }
      ]
    }
  }
}

Capability:

{ "permissions": ["deep-link:default"] }

Handling deep links in Rust:

use tauri_plugin_deep_link::DeepLinkExt;

app.deep_link().on_open_url(|event| {
    println!("Deep link: {:?}", event.urls());
});

Platform notes:

• macOS: registers URL scheme in Info.plist automatically
• Windows: registry entry created during install
• Linux: .desktop file update required
• iOS/Android: configure in respective platform files (AndroidManifest.xml or Info.plist)

Section 4: Custom Protocols

Scope note: Custom protocol (tauri:// and custom schemes via invoke_filter or asset_protocol) is a more advanced feature. The primary official pattern is the built-in asset protocol for serving local files. Custom protocol handlers require careful security consideration.

Show asset protocol access (most common use case):

// tauri.conf.json
{
  "app": {
    "security": {
      "assetScope": ["$APPDATA/assets/**", "$RESOURCE/**"]
    }
  }
}

// Access local file via asset protocol
const imgSrc = convertFileSrc('/path/to/image.png');

Note: Full custom protocol registration (tauri::Builder::register_uri_scheme_protocol) is available but underdocumented in official v2+ docs as of 2026-04-02. Prefer asset protocol for local file serving.