tauri-core-runtime

Quick Reference

Builder Method Summary (Tauri 2.x)

Method	Purpose	Example
Builder::default()	Create default builder	tauri::Builder::default()
.setup(F)	App initialization hook	.setup(|app| { Ok(()) })
.invoke_handler(F)	Register command handlers	.invoke_handler(generate_handler![cmd1])
.manage(T)	Register managed state	.manage(MyState::default())
.plugin(P)	Register a plugin	.plugin(my_plugin::init())
.menu(F)	Set application menu	.menu(|app| MenuBuilder::new(app).build())
.on_window_event(F)	Window event handler	.on_window_event(|window, event| { })
.on_menu_event(F)	Menu event handler	.on_menu_event(|app, event| { })
.on_webview_event(F)	Webview event handler	.on_webview_event(|webview, event| { })
.on_page_load(F)	Page load handler	.on_page_load(|webview, payload| { })
.on_tray_icon_event(F)	Tray icon event handler	.on_tray_icon_event(|app, event| { })
.any_thread()	Allow running on non-main thread	.any_thread()
.build(Context)	Build without running (returns App)	.build(generate_context!())
.run(Context)	Build and run the app	.run(generate_context!())

Manager Trait Key Methods

Method	Returns	Available On
app_handle()	&AppHandle<R>	App, AppHandle, Window, WebviewWindow, Webview
state::<T>()	State<'_, T>	All Manager implementors
try_state::<T>()	Option<State<'_, T>>	All Manager implementors
manage(T)	bool	All Manager implementors
get_webview_window(label)	Option<WebviewWindow<R>>	All Manager implementors
webview_windows()	HashMap<String, WebviewWindow<R>>	All Manager implementors
get_window(label)	Option<Window<R>>	All Manager implementors
get_focused_window()	Option<Window<R>>	All Manager implementors
config()	&Config	All Manager implementors
path()	&PathResolver<R>	All Manager implementors
package_info()	&PackageInfo	All Manager implementors

AppHandle Properties

Property	Description
Clone	Can be cloned freely
Send + Sync	Safe to pass across threads
Implements Manager	Full access to state, windows, config
Implements Emitter	Can emit events
Implements Listener	Can listen for events

Critical Warnings

NEVER call .invoke_handler() more than once on a Builder -- only the last call takes effect. Put ALL commands in a single generate_handler![].

NEVER use Arc to wrap managed state -- Tauri already wraps state in Arc internally. Use app.manage(data), not app.manage(Arc::new(data)).

NEVER access managed state with the wrong wrapper type -- State<'_, MyState> when you registered Mutex<MyState> causes a runtime panic, not a compile error.

ALWAYS clone AppHandle before moving it into a thread or async block -- app.handle().clone() is the correct pattern.

ALWAYS use #[cfg_attr(mobile, tauri::mobile_entry_point)] on the run() function in lib.rs when targeting mobile platforms.

NEVER perform heavy I/O in setup() synchronously without spawning a thread -- it blocks app startup.

---

Essential Patterns

Pattern 1: Standard Application Entry Point (Tauri 2.x)

// src-tauri/src/lib.rs
mod commands;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .manage(AppState::default())
        .plugin(tauri_plugin_opener::init())
        .invoke_handler(tauri::generate_handler![
            commands::greet,
            commands::fetch_data,
        ])
        .setup(|app| {
            let handle = app.handle().clone();
            // Initialization logic here
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

// src-tauri/src/main.rs
fn main() {
    app_lib::run();
}

Pattern 2: The setup() Hook

The setup hook runs after the app is initialized but before windows are shown. It receives &mut App<R> and returns Result<(), Box<dyn Error>>. Any error aborts app startup.

.setup(|app| {
    // 1. Access AppHandle for thread-safe operations
    let handle = app.handle().clone();

    // 2. Register state that depends on app paths
    let db_path = app.path().app_data_dir()?.join("data.db");
    app.manage(Database::new(&db_path)?);

    // 3. Spawn a background thread (uses cloned AppHandle)
    std::thread::spawn(move || {
        loop {
            handle.emit("heartbeat", ()).unwrap();
            std::thread::sleep(std::time::Duration::from_secs(30));
        }
    });

    // 4. Create additional windows programmatically
    let _settings = tauri::webview::WebviewWindowBuilder::new(
        app,
        "settings",
        tauri::WebviewUrl::App("settings.html".into()),
    )
    .title("Settings")
    .inner_size(600.0, 400.0)
    .visible(false)
    .build()?;

    Ok(())
})

Pattern 3: AppHandle in Threads and Async Blocks

AppHandle is Clone + Send + Sync, making it the primary handle for background work.

// In setup() or from a command
let handle = app.handle().clone();

// Std thread
std::thread::spawn(move || {
    let state = handle.state::<MyState>();
    handle.emit("background-update", "data").unwrap();
    if let Some(window) = handle.get_webview_window("main") {
        window.set_title("Updated").unwrap();
    }
});

// Tokio async task
let handle = app.handle().clone();
tokio::spawn(async move {
    let result = some_async_work().await;
    handle.emit("async-done", result).unwrap();
});

Pattern 4: Window Event Callbacks

.on_window_event(|window, event| {
    match event {
        tauri::WindowEvent::CloseRequested { api, .. } => {
            // Prevent close and hide instead (e.g., tray app)
            api.prevent_close();
            window.hide().unwrap();
        }
        tauri::WindowEvent::Focused(focused) => {
            if *focused {
                println!("{} gained focus", window.label());
            }
        }
        tauri::WindowEvent::Destroyed => {
            println!("{} was destroyed", window.label());
        }
        _ => {}
    }
})

Pattern 5: Build vs Run

Use .build() when you need access to the App instance before running, or when you need the run callback for lifecycle events like exit.

// .run() -- simple, no run callback
tauri::Builder::default()
    .run(tauri::generate_context!())
    .expect("error running app");

// .build() + .run() -- access to RunEvent for exit handling
let app = tauri::Builder::default()
    .build(tauri::generate_context!())
    .expect("error building app");

app.run(|app_handle, event| {
    match event {
        tauri::RunEvent::ExitRequested { api, .. } => {
            // Prevent exit (e.g., keep running in tray)
            api.prevent_exit();
        }
        tauri::RunEvent::Exit => {
            // Final cleanup before process ends
            println!("Application exiting");
        }
        _ => {}
    }
});

Pattern 6: Exit and Restart

// Exit from a command
#[tauri::command]
fn quit_app(app: tauri::AppHandle) {
    app.exit(0); // 0 = success exit code
}

// Restart (requires tauri-plugin-process)
#[tauri::command]
fn restart_app(app: tauri::AppHandle) {
    app.restart();
}

// Frontend exit/restart (requires @tauri-apps/plugin-process)
import { exit, relaunch } from '@tauri-apps/plugin-process';

await exit(0);
await relaunch();

---

Async Runtime

Tauri 2.x uses tokio as the async runtime. Async commands are automatically spawned on the tokio runtime -- you do NOT need to configure tokio yourself.

The tauri::async_runtime module provides direct access when needed:

tauri::async_runtime::spawn(async {
    // Runs on the tokio runtime
});

ALWAYS use async commands for I/O, network, or long-running operations. Sync commands run on the main thread and will freeze the UI if they block.

ALWAYS use #[tauri::command(async)] on a sync function if you want it to run on the async runtime instead of the main thread:

#[tauri::command(async)]
fn heavy_sync_computation(data: Vec<u8>) -> Vec<u8> {
    // Runs on tokio runtime, not main thread
    expensive_transform(data)
}

---

WindowEvent Variants (Tauri 2.x)

Variant	Fields	Description
Resized	PhysicalSize<u32>	Window client area resized
Moved	PhysicalPosition<i32>	Window position changed
CloseRequested	api: CloseRequestApi	Close requested; call api.prevent_close() to cancel
Destroyed	--	Window has been destroyed
Focused	bool	true = gained focus, false = lost
ScaleFactorChanged	scale_factor, new_inner_size	DPI/display scale changed
DragDrop	DragDropEvent	File drag-and-drop event
ThemeChanged	Theme	System theme changed (not on Linux)

---

Reference Links

• references/methods.md -- Builder methods, Manager trait methods, AppHandle methods
• references/examples.md -- Lifecycle patterns, setup hook, background tasks
• references/anti-patterns.md -- Lifecycle mistakes and how to avoid them

Official Sources

• https://v2.tauri.app/develop/
• https://docs.rs/tauri/latest/tauri/struct.Builder.html
• https://docs.rs/tauri/latest/tauri/struct.AppHandle.html
• https://docs.rs/tauri/latest/tauri/trait.Manager.html