Commands are the bridge between JavaScript and Rust in your Tauri app. This post gives a thorough overview of building Tauri commands. This post includes many examples. For omitted details, refer to the accompanying repo. I'll also cover some pitfalls that I know left me scratching my head.
To make a command, you have to write the function with the #[tauri::command] macro, register it in the tauri::Builder, then call it from JavaScript.
Let's take a look at the greet command shipped with every create-tauri-app template.
First, in src-tauri/src/lib.rs:
#[tauri::command]fn greet(name: &str) -> String { format!("Hello, {}! You've been greeted from Rust!", name)} #[cfg_attr(mobile, tauri::mobile_entry_point)]pub fn run() { tauri::Builder::default() .plugin(tauri_plugin_shell::init()) .invoke_handler(tauri::generate_handler![greet]) // greet command registered here .run(tauri::generate_context!()) .expect("error while running tauri application");}The command starts with the #[tauri::command] macro. It is a function that accepts the name argument and returns a String using the format! macro. Then it's registered inside the invoke_handler() call using the tauri::generate_handler! macro.
Next, we can use it in our src/main.ts file:
import { invoke } from "@tauri-apps/api/core"; let greetInputEl: HTMLInputElement | null;let greetMsgEl: HTMLElement | null; async function greet() { if (greetMsgEl && greetInputEl) { greetMsgEl.textContent = await invoke("greet", { name: greetInputEl.value, }); }}The default TypeScript template includes a function that uses invoke() to call our command. It takes the command name and an object for arguments (e.g., name). Since invoke() returns a Promise, use await or .then() to handle it.
Now that we have the basic overview, let's dive into more details.
Creating a Commands Module
Since we're creating a lot of commands, let's create a commands module and move our greet command into it. Create the commands.rs file next to lib.rs and move greet to it.
#[tauri::command]pub fn greet(name: &str) -> String { format!("Hello, {}! You've been greeted from Rust!", name)}Since we moved the command to its own file, we need to add the pub keyword.
Then we can update our lib.rs file:
mod commands; // New! #[cfg_attr(mobile, tauri::mobile_entry_point)]pub fn run() { tauri::Builder::default() .plugin(tauri_plugin_shell::init()) .invoke_handler(tauri::generate_handler![commands::greet]) // Changed! .run(tauri::generate_context!()) .expect("error while running tauri application");}Here we just added mod commands; and updated the namespace for our greet command to commands::greet.
Here's the first pitfall: if you create a command inside the lib.rs file and use the pub keyword, you'll get a confusing compiler error. For example, if we have this in lib.rs:
#[tauri::command]pub fn foo() {}Our error will look like this:
error[E0255]: the name `__cmd__foo` is defined multiple times --> src/lib.rs:5:8 |4 | #[tauri::command] | ----------------- previous definition of the macro `__cmd__foo` here5 | pub fn foo() {} | ^^^ `__cmd__foo` reimported here | = note: `__cmd__foo` must be defined only once in the macro namespace of this moduleThis is just because you have the pub keyword when you don't need it. The macro will generate a __cmd__foo and call pub use if it's declared pub, then later try to use __cmd_foo inside lib.rs. This works in its own module but not in the same one.
Command Arguments
Now let's look a bit deeper at passing arguments to our commands. Let's create a greet2() command that accepts a first and last name inside commands.rs:
#[tauri::command]pub fn greet2(first_name: &str, last_name: &str) -> String { format!("The name is {last_name}, {first_name} {last_name}")}Then register it in lib.rs:
#[cfg_attr(mobile, tauri::mobile_entry_point)]pub fn run() { tauri::Builder::default() .plugin(tauri_plugin_shell::init()) .invoke_handler(tauri::generate_handler![commands::greet, commands::greet2]) .run(tauri::generate_context!()) .expect("error while running tauri application");}Now call it inside our main.ts file. I made the greet() and greet2() functions append to the container so we can see both outputs:
let greetMsgEl: HTMLElement | null; async function greet() { let msg: string = await invoke("greet", { name: "Kramer", }); if (greetMsgEl) { greetMsgEl.innerHTML += msg + "<br>"; }} async function greet2() { let msg = await invoke("greet2", { firstName: "James", lastName: "Bond", }); if (greetMsgEl) { greetMsgEl.innerHTML += msg + "<br>"; }} window.addEventListener("DOMContentLoaded", () => { greetMsgEl = document.querySelector("#greet-msg"); greet(); greet2();});Notice that when invoking the greet2 command, we pass firstName as camelCase and not as snake_case. By default, this is how Tauri expects command arguments to be passed from the frontend. If you want to use snake_case in your arguments, you can update the macro to look like this:
#[tauri::command(rename_all = "snake_case")]pub fn greet2(...) {...}Accepting Structs
Tauri commands can accept anything that is serde::Deserialize, so we can make custom structs that derive that trait to accept it as an argument.
For example, if we collected user preferences for the app into a single struct, we could do something like this in our commands.rs:
use serde::{Deserialize, Serialize}; #[derive(Debug, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct Preferences { pub first_name: String, pub theme: Theme,} #[derive(Debug, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub enum Theme { Light, Dark,} #[tauri::command]pub fn save_preferences(preferences: Preferences) { println!("Saving user's preferences {preferences:#?}");}Here we derive Debug for our print statement, Serialize assuming we'd like to be able to return the preferences from a command, and Deserialize so we can accept the struct. We also do the same for the enum Theme. We also use the macro #[serde(rename_all = "camelCase")] so we can use camelCase on the frontend consistently.
After we register the save_preferences command, we can call it on the frontend like so:
async function savePreferences() { await invoke("save_preferences", { preferences: { firstName: "Kramer", theme: "dark", }, });}Because we renamed to camelCase, we can use firstName as expected, but we can also use the lowercase "dark" instead of "Dark" for the enum.
Async Commands
Tauri commands can also be declared as async. It's recommended to use async for commands that can take some time to finish, to prevent UI freezes.
To demonstrate this, we can create a synchronous command that will put the thread to sleep for 3 seconds:
use std::{thread::sleep, time::Duration}; #[tauri::command]pub fn blocking_cmd() -> String { sleep(Duration::from_secs(3)); "Done!".into()}Register it and then call it from the frontend:
async function blocking() { console.log(await invoke("blocking_cmd"));}With this, we'll have a window that will open and freeze for 3 seconds before resuming like normal. But all we have to do to fix that is make the command async:
#[tauri::command]pub async fn non_blocking_cmd() -> String { sleep(Duration::from_secs(3)); "Done!".into()}Register that, and back in main.ts:
async function non_blocking() { console.log(await invoke("non_blocking_cmd"));}Now calling that, everything else will remain snappy while that command does its work on a separate thread.
One thing to note with async commands is that if you are using borrowed data, like &str or tauri::State<'_, AppState>, you'll need to have a return type of Result<T, E>. You can read more about that in Tauri's documentation.
Getting the AppHandle
The AppHandle can be useful for doing many things within Tauri, like creating windows or getting the app's data directory.
use tauri::{AppHandle, Manager}; #[tauri::command]pub fn using_app_handle(app: AppHandle) -> tauri::Result<()> { let dir = app.path().app_data_dir()?; println!("The data dir is located at {dir:?}"); // do more things. Ok(())}Getting the Window
You can also get the Webview window that called the invoke() function. This can be handy if you wish to do actions to a specific window when you have multiple.
#[tauri::command]pub fn hide_window(window: tauri::WebviewWindow) { window.hide();}Getting App State
You can also pass application state directly into a command.
First, you would need to define your state in lib.rs and then manage it inside a closure of the setup() function.
pub struct AppState { pub foo: String,} #[cfg_attr(mobile, tauri::mobile_entry_point)]pub fn run() { tauri::Builder::default() .plugin(tauri_plugin_shell::init()) .invoke_handler(tauri::generate_handler![...]) .setup(|app| { app.manage(AppState { foo: "Bar".into() }); Ok(()) }) .run(tauri::generate_context!()) .expect("error while running tauri application");}Then we can write a command that accepts our state:
use crate::AppState; #[tauri::command]pub fn using_state(state: tauri::State<'_, AppState>) { println!("app state: {}", state.foo);}If you are using async in your command with managed state, we'd have to add a Result<T, E> as our return type. It would look something like this:
#[tauri::command]pub async fn using_state(state: tauri::State<'_, AppState>) -> Result<(), ()> { println!("app state: {}", state.foo);}One thing to note is that if you call this command but you didn't manage AppState yet, it will panic and crash your application. You will get an error message like this:
state not managed for field `state` on command `using_state`. You must call `.manage()` before using this commandError Handling
As we've seen with async commands, we sometimes have to return a Result<T, E>, but often we want to return a helpful error to the frontend if something fails.
#[tauri::command]pub fn errors() -> Result<(), String> { Err("Bad chicken, mess you up!".into())}Then you can wrap your command in a try-catch in your frontend:
async function errors() { try { await invoke("errors"); } catch (e) { console.error(e); }}If you want to see how to handle errors inside commands in depth, read this post.
Conclusion
We covered a lot of ground, but commands are the main way for our frontends to communicate with the Rust core of every Tauri app. Hopefully, this post will serve as a handy reference in the future.