tauri-macros

Active contributors: Lucas Fernandes Nogueira, Amr Bashir

Purpose

crates/tauri-macros is the home of every proc macro Tauri ships. Concretely:

• #[tauri::command] — turn a Rust function into a Tauri command callable from JS.
• tauri::generate_handler! — register a slice of commands with the IPC dispatcher.
• tauri::generate_context! — read tauri.conf.json and embed everything Builder::build needs.
• tauri::include_image! — embed an image asset by path.
• tauri::mobile_entry_point — emit the platform-specific entry symbol on Android/iOS.

Directory layout

crates/tauri-macros/
├── Cargo.toml
├── src/
│   ├── lib.rs       # the proc-macro front door (#[command], generate_handler!, …)
│   ├── command/     # parsing for #[tauri::command]
│   ├── command_module.rs
│   ├── context.rs   # generate_context!
│   ├── menu.rs
│   └── runtime.rs
└── build.rs

Key macros

Macro	Defined in	What it does
#[command]	crates/tauri-macros/src/command/mod.rs	Wraps a function so it can be invoked from JS. Generates an internal type that decodes args and dispatches.
generate_handler!	crates/tauri-macros/src/command/handler.rs	Produces a closure that maps a command name to its #[command]-generated dispatcher.
generate_context!	crates/tauri-macros/src/context.rs	Calls into tauri-codegen to embed tauri.conf.json, frontend assets, ACL, default window icon, etc.
include_image!	crates/tauri-macros/src/lib.rs	Compile-time image::Image from a file path.
mobile_entry_point	crates/tauri-macros/src/lib.rs	Emits the platform-specific entry symbol for Android/iOS apps.

How it works

#[tauri::command] rewrites the user function into a wrapper that:

1. Looks up the named arguments from the incoming serde_json::Value.
2. Resolves Tauri-specific extractors via tauri::ipc::CommandArg (e.g. State<T>, Window, AppHandle, Webview).
3. Calls the original function.
4. Serialises the return value (or error) back into the IPC response.

generate_handler! macro-expands to a match over command names. Misnamed commands fail at compile time, not runtime.

graph LR
    src["fn my_cmd(state: State<MyState>, name: String) -> ..."] -->|"#[command]"| Wrapped["__cmd__my_cmd"]
    Wrapped -->|"generate_handler![my_cmd]"| Handler["dispatcher closure"]
    Handler -->|"Builder::invoke_handler(...)"| App["tauri::App"]

Cargo features

• compression — enable compression in tauri-codegen when generating the embedded asset bundle.
• tracing — emit tracing instrumentation in the generated wrappers.
• custom-protocol — flag passed through from tauri-cli to switch the embedded asset behaviour to production.
• config-json5 / config-toml — accept JSON5 or TOML for tauri.conf.json.
• isolation — enable the isolation pattern code path in generate_context!.

Integration points

• Up: crates/tauri re-exports the macros (pub use tauri_macros::{command, generate_handler}; in crates/tauri/src/lib.rs). Plugin authors use tauri::command etc., not tauri_macros::command.
• Down: depends on tauri-codegen for the heavy lifting in generate_context! and on syn/quote/proc-macro2 for parsing.

Entry points for modification

Goal	Start here
Add a new argument extractor (like State)	crates/tauri-macros/src/command/wrapper.rs plus the CommandArg impl in crates/tauri/src/ipc/command.rs
Change command return-type handling	crates/tauri-macros/src/command/
Adjust how generate_context! embeds assets	crates/tauri-codegen/src/context.rs (called from here)
Add a new convenience macro	crates/tauri-macros/src/lib.rs

See tauri-codegen for the work that backs generate_context!, and systems/ipc-and-commands for the runtime side of #[command].