kevinlin Add a Tauri Command
A command is not usable until it exists in four places. Miss one and it fails at runtime, not at build time — generate_handler! takes any path that compiles, and invoke() takes any string.
The four edits
| Order | File | Edit |
|---|---|---|
| 1 | src-tauri/src/commands/<domain>.rs |
the #[tauri::command] fn |
| 2 | src-tauri/src/commands/mod.rs |
pub mod <domain>; — only when the file is new |
| 3 | src-tauri/src/lib.rs |
one line in tauri::generate_handler![], under the matching // Domain comment |
| 4 | src/lib/tauri-api.ts |
the typed invoke() wrapper |
Pick an existing domain file before creating one. There are 22; a new domain is rare.
Step 1 — the command
Copy templates/command.rs. Two shapes: plain, and path-taking.
Any command that accepts a caller-supplied path MUST go through path_guard. The renderer is untrusted — an agent will pass whatever path its model produced. Model it on the validate_path helper at the top of src-tauri/src/commands/files.rs, and validate before any fs:: call, never after.
Return Result<T, String>. T must be Serialize; shared shapes live in src-tauri/src/types.rs.
Step 2 — register
lib.rs groups the handler list by domain with // comments. Add the line to its group, not the end of the list.
Step 3 — the frontend wrapper
Copy templates/wrapper.ts.
Argument names cross the bridge as camelCase in TS, snake_case in Rust — Tauri converts them. invoke('add_workspace', { folderPath }) binds to folder_path: String. Get this wrong and the argument silently arrives empty.
The function name is camelCase; the invoke string is the exact Rust fn name.
New return types go in src/shared/ and must mirror the Rust struct's serde casing (rename_all = "camelCase" on the Rust side).
Step 4 — verify
cd src-tauri && cargo check # Rust compiles
pnpm typecheck # TS compiles
Then check the wiring, which neither compiler sees:
grep -c '<fn_name>' src-tauri/src/lib.rs src/lib/tauri-api.ts # both must be >= 1
Rust changes need an app restart (pnpm tauri dev); the frontend hot-reloads. Do not report the command as working until you have seen it return in the running app or in a test.
Capabilities
If the command calls a Tauri plugin API (shell, dialog, opener, updater, process), the calling window needs the permission in src-tauri/capabilities/. Those files are protected — do not edit them. Say which permission is needed and which window needs it, and let the user make the change.
Plain Rust (std::fs, rusqlite, reqwest) needs no capability entry.
Tests
Rust: #[cfg(test)] mod tests in the same file, cd src-tauri && cargo test. Pure logic — extract it out of the command body so it is testable without a State.
Frontend: __tests__/ next to the code, pnpm test --run.
Common mistakes
| Symptom | Cause |
|---|---|
Command <name> not found |
Step 2 skipped — not in generate_handler![] |
Argument arrives empty or None |
camelCase/snake_case mismatch between the invoke object and the Rust param |
| Command compiles, never reachable | New file, no pub mod line in commands/mod.rs |
| Works in dev, fails on a user's machine | Path used without path_guard — outside the sandbox roots |
unknown permission at runtime |
Plugin API called from a window whose capability file does not grant it |