Skip to main content

Crate tauri_plugin_widgets

Crate tauri_plugin_widgets 

Source
Expand description

§tauri-plugin-widgets

A Tauri v2 plugin for building native widgets on Android, iOS, macOS, Windows, and Linux from a single JSON UI configuration.

Empty placeholders for Adaptive Cards are avoided when the rasterize feature is enabled (chart/canvas/gauge/shape/zstack/gradients → PNG).

§Overview

  • Widget Config API — send a declarative WidgetConfig describing layouts and elements. The native widget renders it using SwiftUI (Apple), RemoteViews (Android), or HTML/CSS (desktop).

  • Data API — key-value storage shared with native widget extensions via the App Group shared container (Apple), SharedPreferences (Android), or JSON files (desktop).

  • Desktop widget windows — frameless, transparent Tauri webview windows that render the same JSON config as HTML/CSS.

§Architecture

The plugin acts as a library, not a builder. It does NOT compile or inject widget extensions at runtime. Instead, it provides:

  1. Rust side — commands for data storage and WidgetKit reload
  2. Swift Package (swift/TauriWidgets) — public SwiftUI views and models that developers import into their own Widget Extension target
  3. Templates (templates/) — ready-to-use scripts and Swift files

This follows Apple’s guidelines: the extension is built by Xcode, signed with the developer’s certificate, and included in the app bundle at compile time.

§Quick Start (Rust)

tauri::Builder::default()
    .plugin(tauri_plugin_widgets::init());

§iOS Setup

  1. Open gen/apple/*.xcodeproj in Xcode
  2. File → New → Target → Widget Extension
  3. Add swift/ as a Local Swift Package dependency
  4. Add TauriWidgets library to the Widget Extension target
  5. Enable App Groups in both targets (App + Widget Extension)
  6. Use the template from templates/ios-widget/MyWidget.swift

§macOS Setup (“Satellite Project”)

Tauri for macOS does not generate an .xcodeproj, so the widget extension must be built as a separate Xcode project:

  1. Create src-tauri/widget-extension/ with an Xcode project containing a Widget Extension target
  2. Add swift/ as a Local Swift Package dependency
  3. Enable App Groups in both the main app entitlements and the widget extension entitlements
  4. build-widget.sh runs via beforeBundleCommand (builds + signs .appex)
  5. bundle.macOS.files copies the .appex into Contents/PlugIns/ during a normal tauri build (Tauri nested-codesigns PlugIns)
  6. Set plugins.widgets.transport (appGroup with Team ID, or widgetContainer for ad-hoc) and plugins.widgets.appGroup

§Rust API

Build a config with typed helpers (compile-checked, not executed here):

use tauri_plugin_widgets::models::{text, vstack, WidgetConfig};

let _cfg = WidgetConfig::small(vstack(vec![
    text("72°").font_size(36.0).into(),
]));

Then call WidgetExt::widget on an AppHandle to set_widget_config / reload_all_timelines (requires a running Tauri app).

Re-exports§

pub use adaptive_card::to_adaptive_card;
pub use adaptive_card::to_adaptive_card_for_size;
pub use adaptive_card::TranspileResult;
pub use apply::ApplyOutcome;
pub use apply::ReloadOutcome;
pub use apply::SkipReason;
pub use config::TransportKind;
pub use config::WidgetsPluginConfig;
pub use error::Error;
pub use error::Result;
pub use receipt::SkippedElement;
pub use receipt::WidgetRenderReceipt;
pub use store::WidgetActionEnvelope;
pub use trace::TraceEntry;
pub use trace::TraceEvent;
pub use trace::WidgetTrace;
pub use transport::Receipt;
pub use transport::Transport;
pub use desktop::Widget;desktop

Modules§

adaptive_card
Adaptive Cards transpiler (Windows Widgets Board). IR → Adaptive Card 1.5 transpiler for Windows Widgets Board.
apply
Outcomes for set_widget_config (written / reload / skip). Outcomes for set_widget_config — no silent Ok(true).
capabilities
Element × platform capability matrix. Platform capability matrix for widget IR elements.
codegen
TypeScript IR emitter (gen-ts). Emit TypeScript IR types from an explicit Rust IR_ELEMENTS spec (SoT with models).
config
Plugin configuration (plugins.widgets in tauri.conf.json). Plugin config from tauri.conf.json → plugins.widgets.
desktopdesktop
error
Plugin error type. Error types for the widget plugin.
icons
SF Symbol → Material / emoji resolve for non-Apple hosts. SF Symbol → cross-platform icon resolve (Material ligature + emoji fallback).
image_prefetch
Host-side remote image prefetch for WidgetKit / desktop store writes. Prefetch remote image.url into data: URIs for hosts that cannot fetch (WidgetKit). Android keeps its own localPath pipeline — Rust prefetch is a no-op there so we do not inflate SharedPreferences / Binder with base64.
linuxLinux and linux
Linux desktop-widget pinning: X11 _NET_WM_* hints and optional gtk-layer-shell.
models
Widget IR models (WidgetConfig, WidgetElement, …).
normalize
Host-side IR normalization (textStyle → points, semantic colors → adaptive hex). Host-side IR normalization before store write.
rasterize
SVG / PNG helpers for Adaptive Cards fallbacks. SVG builders + optional PNG rasterize for Adaptive Cards Image data URIs.
receipt
Render receipts written by native / desktop surfaces. Cross-platform render receipts (diagnostics, not a critical path).
snapshot
Canonical layout dumps for snapshot tests. Canonical layout dump for core WidgetConfig snapshot tests.
store
Shared key-value store helpers and action envelopes. Shared storage contract for widget data across platforms.
trace
Host black-box journal (WIDGET_DEBUG / debug builds). Host-side black-box journal for widget delivery diagnostics.
transport
macOS / desktop config transport selection. Apple host→widget transport: one driver, chosen by config (not runtime fan-out).

Traits§

WidgetExt
Extension trait for convenient access from any Tauri manager.

Functions§

init
Initialize the widgets plugin. Register it with tauri::Builder::plugin().