tauri-runtime

Active contributors: Lucas Fernandes Nogueira, Amr Bashir

Purpose

crates/tauri-runtime defines the trait surface that decouples the Tauri core from any specific windowing/webview backend. The crate exposes Runtime, RuntimeHandle, WindowDispatch, WebviewDispatch, the pending/detached window and webview structs, the event types, and the DPI/monitor utilities. The default implementation lives in tauri-runtime-wry; third parties can implement an alternative by satisfying the same trait set.

The crate documents up front that none of its API is "stable" — the major version only signals which Tauri major it pairs with. Plugin authors should depend on tauri, not on tauri-runtime.

Directory layout

crates/tauri-runtime/
├── Cargo.toml
├── src/
│   ├── lib.rs       # 1,004 lines: Runtime, RuntimeHandle, errors, RunIteration, EventLoopProxy, …
│   ├── webview.rs   # PendingWebview, DetachedWebview, WebviewDispatch trait, attributes
│   ├── window.rs    # PendingWindow, DetachedWindow, WindowBuilder, RawWindow, WindowEvent
│   ├── monitor.rs   # Monitor type
│   └── dpi.rs       # PhysicalSize/Position, LogicalSize/Position, Rect, Size
└── build.rs

Key abstractions

Type / Trait	File	Role
Runtime<T> (trait)	crates/tauri-runtime/src/lib.rs	The top-level event loop. Owns windows/webviews, runs to completion.
RuntimeHandle<T>	crates/tauri-runtime/src/lib.rs	A Send/Sync handle to the runtime, used from worker threads to create windows or events.
EventLoopProxy<T>	crates/tauri-runtime/src/lib.rs	Sends user-defined events into the runtime's event loop.
PendingWindow / DetachedWindow	crates/tauri-runtime/src/window.rs	A window that has been requested vs. a window that has actually been created.
PendingWebview / DetachedWebview	crates/tauri-runtime/src/webview.rs	Same split for webviews.
WindowDispatch / WebviewDispatch	crates/tauri-runtime/src/window.rs, webview.rs	The "tell the runtime to do X to this window/webview" trait — set title, navigate, close, etc.
WindowEvent / WebviewEvent	crates/tauri-runtime/src/window.rs	Translated from TAO/WRY events into a backend-agnostic enum.
ProgressBarState / ProgressBarStatus	crates/tauri-runtime/src/lib.rs	Cross-platform progress bar (taskbar/dock).
UserAttentionType	crates/tauri-runtime/src/lib.rs	Window attention requests (bouncing dock, flashing taskbar).
DeviceEventFilter	crates/tauri-runtime/src/lib.rs	When to deliver device events.
Error	crates/tauri-runtime/src/lib.rs	Backend-agnostic error enum used by the trait.
Cookie	re-export	cookie::Cookie is re-exported; bumping the dep is a documented breaking change.

How it works

The trait carves the boundary cleanly: Runtime returns RuntimeHandles, WindowDispatches, and WebviewDispatches. Tauri core calls those handles for everything (set title, eval JS, request progress bar, register URI scheme handler) and never touches the underlying TAO/WRY types directly.

graph LR
    Core["tauri (core)"] -->|"WindowDispatch::set_title(...)"| Trait["tauri-runtime::WindowDispatch"]
    Trait --> Wry["tauri-runtime-wry impl"]
    Wry --> TAO["TAO Window"]

Cargo features:

• devtools — exposes the open_devtools/close_devtools methods on the dispatch traits.
• macos-private-api — gate the macOS-only methods that depend on private APIs (transparent windows, etc.).

Integration points

• Up: consumed by crates/tauri (tauri-runtime = { ... } in crates/tauri/Cargo.toml) and by crates/tauri-runtime-wry.
• Down: depends only on tauri-utils, raw-window-handle, serde, cookie, and http.

Entry points for modification

• Adding a new method that windows/webviews can perform → add it on WindowDispatch or WebviewDispatch here, then implement in tauri-runtime-wry.
• Adding a new event variant → add it to WindowEvent / WebviewEvent here and translate from TAO/WRY in tauri-runtime-wry/src/lib.rs.
• Adding configuration that needs to flow into a builder → add a setter on WindowBuilder (the trait) here.

See tauri-runtime-wry for the actual implementation, and tauri for the consumer.