TauRPC

To avoid cluttering a single trait, use the taurpc::Router to create nested command and event structures.

1. Define a root trait (without a path).
2. Define nested traits using #[taurpc::procedures(path = "...")]. Use #[taurpc(event)] on methods to mark them as events.
3. Create a taurpc::Router and use .merge(handler) to combine multiple handlers.
4. Use router.into_handler() in your Tauri invoke_handler.

On the frontend, nested paths are accessed via the proxy object (e.g., taurpc.path.method()). Events are accessed via .on() (e.g., taurpc.path.method.on(...)).

// Root procedures
#[taurpc::procedures]
trait Api {
    async fn hello_world();
}

#[derive(Clone)]
struct ApiImpl;

#[taurpc::resolvers]
impl Api for ApiImpl {
    async fn hello_world(self) {
        println!("Hello world");
    }
}

// Nested procedures
#[taurpc::procedures(path = "events")]
trait Events {
    #[taurpc(event)]
    async fn event();
}

#[derive(Clone)]
struct EventsImpl;

#[taurpc::resolvers]
impl Events for EventsImpl {}

#[tokio::main]
async fn main() {
    let router = taurpc::Router::new()
        .merge(ApiImpl.into_handler())
        .merge(EventsImpl.into_handler());

    #[cfg(debug_assertions)]
    taurpc::Exporter::new()
        .export(&router, "../src/bindings.ts")
        .unwrap();

    tauri::Builder::default()
        .invoke_handler(router.into_handler())
        .run(tauri::generate_context())
        .expect("error while running tauri application");
}

TauRPC provides a fully-typed IPC layer for Tauri commands and events. To get started, follow these steps:

1. Add dependencies to your src-tauri/Cargo.toml:

   • taurpc
   • specta (with derive feature)
   • tokio (with full feature)

2. Define and implement your API in Rust using the #[taurpc::procedures] trait and #[taurpc::resolvers] implementation.

3. Export TypeScript bindings using taurpc::Exporter. It is recommended to wrap this in #[cfg(debug_assertions)] so bindings are generated during development.

4. Register the handler in your Tauri builder using taurpc::create_ipc_handler(api_handler).

5. Install the frontend package via pnpm install taurpc.

6. Use the proxy in your TypeScript code by importing createTauRPCProxy from your generated bindings file.

// src-tauri/src/main.rs

#[taurpc::procedures]
trait Api {
    async fn hello_world();
}

#[derive(Clone)]
struct ApiImpl;

#[taurpc::resolvers]
impl Api for ApiImpl {
    async fn hello_world(self) {
        println!("Hello world");
    }
}

#[tokio::main]
async fn main() {
    let api_handler = ApiImpl.into_handler();

    #[cfg(debug_assertions)]
    taurpc::Exporter::new()
        .export(&api_handler, "../src/bindings.ts")
        .unwrap();

    tauri::Builder::default()
        .invoke_handler(taurpc::create_ipc_handler(api_handler))
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

You can share state between procedures by adding fields to your API implementation struct. If the state needs to be mutable, use a thread-safe container like Arc<Mutex<T>>.

TauRPC procedures can also accept Tauri-specific arguments like window, app_handle, and webview_window directly in the method signature, just like standard Tauri commands.

use std::sync::Arc;
use tokio::sync::Mutex;
use tauri::{Manager, Runtime, State, Window};

type MyState = Arc<Mutex<String>>;

#[taurpc::procedures]
trait Api {
    async fn with_state();
    async fn with_window<R: Runtime>(window: Window<R>);
}

#[derive(Clone)]
struct ApiImpl {
    state: MyState
};

#[taurpc::resolvers]
impl Api for ApiImpl {
    async fn with_state(self) {
        // Access state via self.state
    }

    async fn with_window<R: Runtime>(self, window: Window<R>) {
        // Use the window object
    }
}

#[tokio::main]
async fn main() {
    tauri::Builder::default()
        .invoke_handler(taurpc::create_ipc_handler(
            ApiImpl {
                state: Arc::new(Mutex::new("state".to_string())),
            }
            .into_handler(),
        ))
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

TauRPC supports Tauri Channels, allowing you to pass typed callback functions from your TypeScript frontend to your Rust backend.

1. Define the data structure for the channel using #[taurpc::ipc_type].
2. In your procedure trait, accept a Channel<T> parameter.
3. In the resolver, use on_event.send(data) to push updates to the frontend.
4. On the frontend, pass an async callback function to the command.

// Rust: Define the type and the procedure
#[taurpc::ipc_type]
struct Update {
    progress: u8,
}

#[taurpc::procedures]
trait Api {
    async fn update(on_event: Channel<Update>);
}

#[taurpc::resolvers]
impl Api for ApiImpl {
    async fn update(self, on_event: Channel<Update>) {
        for progress in [15, 20, 35, 50, 90] {
            on_event.send(Update { progress }).unwrap();
        }
    }
}

// TypeScript: Call the command with a callback
let taurpc = createTauRPCProxy();
await taurpc.update((update) => {
  console.log(update.progress);
});

You can trigger events from your Rust backend to your TypeScript frontend with full type safety. The #[taurpc::procedures] macro automatically generates an event trigger struct.

By default, the trigger struct is named TauRpc{TraitName}EventTrigger. You can customize this name using the event_trigger attribute on the trait.

To define an event, add the #[taurpc(event)] attribute to the method in your trait. Methods marked with #[taurpc(event)] do not require a corresponding resolver implementation.

On the frontend, use the .on() method provided by the generated proxy to listen for these events. The .on() method returns an unlisten function that should be called during component cleanup (e.g., useEffect cleanup in React or onDestroy in Svelte).

// 1. Define the API and custom trigger name
#[taurpc::procedures(event_trigger = ApiEventTrigger)]
trait Api {
    #[taurpc(event)]
    async fn hello_world();
}

#[derive(Clone)]
struct ApiImpl;

#[taurpc::resolvers]
impl Api for ApiImpl {}

#[tokio::main]
async fn main() {
    tauri::Builder::default()
        .invoke_handler(taurpc::create_ipc_handler(ApiImpl.into_handler()))
        .setup(|app| {
            // 2. Use the trigger in the setup block
            let trigger = ApiEventTrigger::new(app.handle());
            trigger.hello_world()?;
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

// 3. Listen on the frontend
const unlisten = await taurpc.hello_world.on(() => {
  console.log('Hello World!')
})

// Cleanup
unlisten()

To define a set of IPC methods for Tauri, use the #[taurpc::procedures] attribute on a Rust trait. This macro parses the trait and its methods to generate the necessary handler logic.

Method Rules and Constraints

• Named Arguments Only: All arguments in the trait methods must be named (e.g., fn my_method(arg: Type)). Unnamed or pattern-based arguments are not supported and will cause a compilation error.
• Async vs Sync:
  • async fn methods resolve on Tauri's async runtime.
  • Standard fn methods respond inline (synchronous).
• Reserved Method Names: You cannot name your trait methods after the following reserved names, as they conflict with generated functions:
  • into_handler
  • setup
  • send_to (used for sending scoped events)
• Skipping Methods: You can use the #[taurpc(skip)] attribute on a method to prevent it from being exported as an IPC method.

#[taurpc::procedures]
trait MyIpcMethods {
    // An async method (resolves on Tauri async runtime)
    async fn get_data(id: u32) -> String;

    // A sync method (responds inline)
    fn ping() -> bool;

    // A method that will be skipped by the macro
    #[taurpc(skip)]
    fn internal_helper();
}