tauri-specta

The CommandSet is the central orchestrator for generating TanStack Query bindings. It manages the lifecycle of command registration, type registration, and constant definition.

Workflow

1. Initialization: Create a set via CommandSet::new(queries, mutations). Commands must be unique to one collection to avoid ambiguous helpers.
2. Augmentation: Before building, you can add:
   • Standalone Types: Use .typ::<T>() for types not reachable via commands/events.
   • Constants: Use .constant(key, value) to export serializable values.
   • Events: Use .events(events) to register frontend event bindings.
   • Casing: Use .function_casing(casing) to control the naming convention of the generated TypeScript helpers.
3. Finalization: Call .build(framework) which returns a tuple: (String, tauri_specta::Builder<R>). The String is the raw TS code for the helpers, and the Builder is used for the actual Tauri integration.

To get started with Tauri Specta, use the Builder to register commands and events, then export the bindings to a file. You must also register the invoke_handler and call mount_events during the Tauri app setup for the bindings to function correctly.

TypeScript Export Example

use tauri_specta::{collect_commands, collect_events, Builder};
use specta_typescript::Typescript;

let mut builder = Builder::new()
    .commands(collect_commands![])
    .events(collect_events![]);

#[cfg(debug_assertions)]
builder
    .export(Typescript::default(), "../src/bindings.ts")
    .expect("Failed to export typescript bindings");

tauri::Builder::default()
    .invoke_handler(builder.invoke_handler()) // Required for commands to work
    .setup(move |app| {
        builder.mount_events(app); // Required for events to work

        Ok(())
    })
    .run(tauri::test::mock_context(tauri::test::noop_assets()))
    .expect("error while running tauri application");

JSDoc Export Example

use tauri_specta::{collect_commands,collect_events,Builder};
use specta_typescript::JSDoc;

let mut builder = Builder::new()
    .commands(collect_commands![])
    .events(collect_events![]);

// exporting to JsDoc
#[cfg(debug_assertions)]
builder
    .export(JSDoc::default(), "../src/bindings.js")
    .expect("Failed to export jsdoc bindings");

tauri::Builder::default()
    .invoke_handler(builder.invoke_handler()) // Required for commands to work
    .setup(move |app| {
        builder.mount_events(app); // Required for events to work

        Ok(())
    })
    .run(tauri::test::mock_context(tauri::test::noop_assets()))
    .expect("error while running tauri application");

To use TypeScript bindings, follow these steps:

1. Annotate your Tauri commands with #[specta::specta].
2. Initialize a Builder and register your commands using collect_commands![].
3. Export the bindings using builder.export() (typically on non-release builds).
4. Register the builder's invoke_handler() with your Tauri application.
5. If using events, call builder.mount_events(app) in the Tauri setup closure.

#![cfg_attr(
    all(not(debug_assertions), target_os = "windows"),
    windows_subsystem = "windows"
)]

use serde::{Deserialize, Serialize};
use specta_typescript::Typescript;
use tauri_specta::{collect_commands, Builder};

#[tauri::command]
#[specta::specta] // < You must annotate your commands
fn hello_world(my_name: String) -> String {
    format!("Hello, {my_name}! You've been greeted from Rust!")
}

fn main() {
    let mut builder = Builder::new()
        // Then register them (separated by a comma)
        .commands(collect_commands![hello_world,]);

    #[cfg(debug_assertions)] // <- Only export on non-release builds
    builder
        .export(Typescript::default(), "../src/bindings.ts")
        .expect("Failed to export typescript bindings");

    tauri::Builder::default()
        // and finally tell Tauri how to invoke them
        .invoke_handler(builder.invoke_handler())
        .setup(move |app| {
            // This is also required if you want to use events
            builder.mount_events(app);

            Ok(())
        })
        .run(tauri::test::mock_context(tauri::test::noop_assets()))
        .expect("error while running tauri application");
}

To make events type-safe:

1. Derive tauri_specta::Event on your event struct.
2. Register the event using collect_events![] on the builder.
3. Call builder.mount_events(app) in the Tauri setup closure.
4. Use the generated events object on the frontend to listen or emit.

use serde::{Serialize, Deserialize};
use specta::Type;
use tauri_specta::{Builder, collect_commands, collect_events, Event};

// Add tauri_specta::Event to your event
#[derive(Serialize, Deserialize, Debug, Clone, Type, Event)]
pub struct DemoEvent(String);

let mut builder = Builder::new()
        // And then register it to your builder
        .events(collect_events![DemoEvent]);

// ... in Tauri setup ...
builder.mount_events(app);

// Backend usage:
DemoEvent("Test".into()).emit(app).unwrap();

Frontend usage:

import { commands, events } from "./bindings";
import { appWindow } from "@tauri-apps/api/window";

// For all windows
events.demoEvent.listen((e) => console.log(e));

// For a single window
events.demoEvent(appWindow).listen((e) => console.log(e));

// Emit to the backend and all windows
await events.demoEvent.emit("Test")

// Emit to a window
await events.demoEvent(appWindow).emit("Test")