Guide

Install

Use the Tauri CLI — it adds the Rust crate and the JS package in one step. Works with any package manager, and with cargo tauri too:

# npm
npm run tauri add tauri-plugin-widgets

# pnpm
pnpm tauri add tauri-plugin-widgets

# yarn
yarn tauri add tauri-plugin-widgets

# bun
bun tauri add tauri-plugin-widgets

# cargo (no Node script required)
cargo tauri add tauri-plugin-widgets

Then finish Register the plugin, Permissions, and (on Apple hosts) Plugin config if the CLI did not wire them for your project layout.

Optional Cargo features: Cargo features.

Manual install

Cargo

# src-tauri/Cargo.toml
[dependencies]
tauri-plugin-widgets = "0.8"

Or:

cd src-tauri && cargo add tauri-plugin-widgets

JavaScript package

pnpm add tauri-plugin-widgets-api
# npm i tauri-plugin-widgets-api
# yarn add tauri-plugin-widgets-api
# bun add tauri-plugin-widgets-api

Register the plugin

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_widgets::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Plugin config

None needed. Defaults:

SettingDefault
plugins.widgets.appGroupgroup.<identifier> from tauri.conf.json
plugins.widgets.transportwidgetContainer on macOS, appGroup on iOS
JS group argumentthe App Group above
JS widgetId argument"default" (matches the Swift / Kotlin templates)

Set appGroup only when the group id differs from group.<identifier>. iOS device widgets need a paid Apple Developer account (App Groups). Details: Plugin config · Transport.

Permissions

src-tauri/capabilities/default.json must list every window label that calls plugin commands — including desktop widget labels from createWidgetWindow:

{
  "identifier": "default",
  "windows": ["main", "weather"],
  "permissions": [
    "core:default",
    "widgets:default"
  ]
}

Use "*" only if you intentionally allow all labels. Missing the widget label → the embedded renderer cannot call getWidgetConfig and the window stays empty.

Full list: Permissions.

Scaffold native extensions

These copy templates into your app under src-tauri/ (they do not leave files only inside node_modules):

npx tauri-widgets init                # every platform this project targets
npx tauri-widgets init-macos          # → src-tauri/macos-widget/ + tauri.macos.conf.json
npx tauri-widgets init-ios            # → src-tauri/ios-widget/ + extension target in gen/apple
npx tauri-widgets init-windows        # → src-tauri/windows-widget/

Guides: Platform setup.

Next: First widget (desktop) or Platform setup.