Tauri v2 Docs — Reference

Purpose

Resolve the exact Tauri v2 documentation page for a task and pull the needed API/config/plugin details into the answer — like Cursor's @Docs for Tauri v2. Tauri v2 docs have an official llms.txt index, so page resolution is reliable, not guessed.

When to use

• Any question or implementation touching Tauri 2.x: Rust side (tauri, tauri-build), JS side (@tauri-apps/api, @tauri-apps/cli), config (tauri.conf.json), permissions/capabilities (ACL), plugins (tauri-plugin-*), or the Tauri CLI.
• Verifying a v2 API signature, config key, or permission identifier before writing code.

Preconditions

• You have web access (WebFetch/WebSearch).
• The project is a Tauri v2 project (check package.json / Cargo.toml if unsure — tauri = "2", @tauri-apps/api@^2). This skill covers v2 only.

Workflow

1. Identify the area the user is working in: setup/config, Rust core API, JS API, plugins, permissions/ACL, CLI/build, or distribution/mobile.
2. Resolve the exact page using the Doc map below. If the map doesn't cover it, fetch the right llms file (llms.txt index, _llms-txt/guides.txt, or _llms-txt/reference.txt) and pick the precise URL — never guess deep links.
3. Fetch the target page with WebFetch, with a focused extraction prompt ("Extract the signature, example code, and config keys for X") — do not dump the whole page into context.
4. For Rust API questions, fetch the relevant module on https://docs.rs/tauri/<installed-version>/tauri/ (use latest only after confirming compatibility with the target) (e.g. app, manager, window, webview, fs, path, process, command, tray, menu, event, image, ipc).
5. Cross-check the result against v2 idioms (see Rules), then answer with code and cite the source URL.

Doc map (verified entry points)

Rules

• v2 only. Use documentation whose content/schema explicitly targets Tauri 2. Do not infer a version solely from the hostname; official sites can redirect or change. Never import v1 examples into a v2 project.
• Version alignment. A v2 project must use only v2 artifacts: tauri crate ^2, @tauri-apps/api/@tauri-apps/cli ^2, tauri-plugin-* v2.x, and the v2 tauri.conf.json schema. Never mix v1 code with v2.
• Resolve URLs via the llms index instead of guessing paths.
• Rust API docs must match the installed/target crate version; use a versioned docs.rs URL when checking version-sensitive APIs. Plugin crates have independent versions and their own docs. Latest is not automatically compatible.
• Plugin questions → the plugin's own guide page under v2.tauri.app (e.g. /plugin/shell/) or its docs.rs crate; plugins are separate crates with separate APIs.
• When embedding fetched content into an answer, cite the source URL.
• If a page 404s or looks stale, fall back to llms-full.txt or a WebSearch limited to site:v2.tauri.app.

Common mistakes

• Copying v1 examples: tauri::api::* modules (fs, path, dialog) are gone in v2 — replaced by tauri::fs, tauri::path, and tauri-plugin-dialog.
• Using app.get_window(...) — v2 uses app.get_webview_window(...) / get_webview_windows().
• Calling invoke from @tauri-apps/api/tauri — v2 imports it from @tauri-apps/api/core.
• Using v1 configuration keys in a v2 project — validate against the target v2 schema. Capabilities can be files or inline entries in app.security.capabilities; do not require a separate file for every capability when the established project uses inline definitions.
• Pulling llms-full.txt wholesale into context — it is huge; fetch targeted pages or the section files only.

Validation

• Run a sample query end-to-end, e.g. "Show a file dialog in Tauri v2" must resolve to tauri-plugin-dialog / @tauri-apps/plugin-dialog (v2), not v1 tauri::api::dialog.
• Confirm https://v2.tauri.app/llms.txt is reachable before relying on it.
• Verify any code you produce compiles against the fetched signatures (cite the page).

Playbook: "my overlay window disappeared" (macOS)

Use this whenever a Tauri overlay/always-on-top window "vanishes" on macOS. The single most decisive step is probing the window FROM OUTSIDE the app with CGWindowList — it reports existence, visibility, alpha, and exact global bounds without any app cooperation.

Step 1 — probe where the window actually is

Save as /tmp/win_diag.swift, run swift /tmp/win_diag.swift (adjust the owner filter):

import AppKit
let all = CGWindowListCopyWindowInfo([.optionAll], kCGNullWindowID) as! [[String: Any]]
for w in all {
    let owner = w[kCGWindowOwnerName as String] as? String ?? ""
    if owner.contains("YourApp") {           // ← your app's process name
        let name = w[kCGWindowName as String] as? String ?? "?"
        let b = w[kCGWindowBounds as String] as? [String: Any] ?? [:]
        let onscreen = w[kCGWindowIsOnscreen as String] as? Bool ?? false
        let alpha = w[kCGWindowAlpha as String] as? Double ?? -1
        print("\(owner) | '\(name)' | onscreen=\(onscreen) alpha=\(alpha) | \(b)")
    }
}

Bounds are global screen coordinates (top-left origin of the main display). Compare against NSScreen.screens.map { $0.frame } for the legal range.

Step 2 — read the verdict

Step 3 — the durable fix for the offscreen case

Persisted overlay positions (localStorage per overlay, e.g. a dragged overlay's saved spot) must be clamped on restore in the Rust set_position path — never trust a saved {x, y}:

// Clamp so at least half the window stays inside the current monitor:
let max_x = (monitor.size().width as i32 - win_w).max(0);
let max_y = (monitor.size().height as i32 - win_h).max(0);
x = x.clamp(-(win_w - min_visible), max_x);
y = y.clamp(-(win_h - min_visible_y), max_y);

A typical instance of this class: an overlay parked at X=-72 (44 px wide = fully invisible) while every gate read "visible" — hotkey handlers and show-watchers kept re-applying the same offscreen point. The clamp in the shared position helper fixed it for every overlay.

Related dev-mode trap (same symptom family)

tauri dev can spawn the app process BEFORE cargo finishes rewriting the binary in place — the running process then executes the OLD code even though the on-disk binary is new (the page cache keeps old pages for the mapped image; the file inode can even match). Before debugging any daemon/window behavior, compare:

ps -axo pid,lstart,command | grep <binary>   # process start time
stat -f "%Sm" <binary>                        # binary mtime — must be OLDER than proc start

If the binary is NEWER than the running process, kill it and let the dev runner respawn before drawing any conclusions about the code.