Platform setup

macOS setup

macOS widgets require a "sidecar" Xcode project — a small project alongside your Tauri app that compiles the Widget Extension (.appex). After init-macos, a normal pnpm tauri build produces an .app (and DMG) with Contents/PlugIns/*.appex already inside.

Important: On macOS, WidgetKit picks up extension widgets from the installed app bundle.
Addable widgets appear only after you build the app and move the resulting .app to /Applications (or install from the DMG).

Requirements: xcodegen (brew install xcodegen)

Step 1: Initialize the widget project

npx tauri-widgets init-macos

Bundle id (<identifier>.widgetkit) and App Group (group.<identifier>) come from tauri.conf.json; pass --bundle-id / --app-group to override.

This creates src-tauri/macos-widget/:

  • Sources/MyWidget.swift — widget code using TauriWidgetProvider (widgetId: "default")
  • project.yml — XcodeGen spec for the .appex
  • build-widget.sh — builds and signs the .appex; regenerates both .entitlements from the App Group on every build

and writes src-tauri/tauri.macos.conf.json (Tauri merges it on macOS only, so Linux / Windows builds are untouched):

{
  "build": {
    "beforeBundleCommand": "./src-tauri/macos-widget/build-widget.sh"
  },
  "bundle": {
    "macOS": {
      "entitlements": "./macos-widget/App.entitlements",
      "files": {
        "PlugIns/TauriWidgetExtension.appex": "./macos-widget/build/Build/Products/Release/TauriWidgetExtension.appex"
      }
    }
  }
}

No plugins.widgets block is needed.

Step 2: Transport (usually nothing to do)

On macOS the host writes widget data straight into the extension's own container (transport: "widgetContainer", the default). This works with ad-hoc and Developer ID signing, as long as the host app is not sandboxed (the Tauri default).

group.* App Group containers need a provisioning profile on macOS: without one, the sandboxed extension cannot open them and shows No configuration. Set "transport": "appGroup" only for a sandboxed Mac App Store build. Details: Apple data transport.

Step 3: Install

WidgetKit lists widgets only from an installed app: build, then move the .app to /Applications (or install the DMG) and launch it once.

Step 4: Build

pnpm tauri build

# Prefer the identity printed by `npx tauri-widgets signing`:
WIDGET_SIGN_IDENTITY="Apple Development: you@example.com (TEAMID)" pnpm tauri build

Pipeline:

  1. Rust + frontend build
  2. build-widget.sh → signed .appex
  3. Tauri copies PlugIns, nested-codesigns, notarizes (if configured), writes .app / DMG

Tip: { "scripts": { "build:macos": "tauri build" } } then pnpm build:macos.

Code Signing

build-widget.sh signs the .appex before bundling. Identity resolution:

  1. WIDGET_SIGN_IDENTITY
  2. APPLE_SIGNING_IDENTITY
  3. Fallback: - (ad-hoc)
npx tauri-widgets signing          # lists identities
security find-identity -v -p codesigning
SigningWidget visibletransportDistribution
Ad-hoc (-)YeswidgetContainer (default)Local only
Developer ID (+ notarization)YeswidgetContainer (default)Direct distribution
Mac App Store (sandboxed host)YesappGroupApp Store

The main app's App.entitlements must not include com.apple.security.app-sandbox with widgetContainer. The widget extension is always sandboxed (WidgetKit requires it).

Debugging the widget separately

cd src-tauri/macos-widget
xcodegen generate
open TauriWidgetExtension.xcodeproj

Select the widget scheme in Xcode, set your app as the Host Application, and run with breakpoints.


When it fails

Widget shows "No configuration"

  • Call setWidgetConfig(...) from your app (with the app launched from /Applications).
  • transport: "appGroup" in a Developer ID / ad-hoc build: remove it (the extension cannot open a group.* container without a provisioning profile).
  • Check that the app is not sandboxed (App.entitlements should not contain com.apple.security.app-sandbox).
  • Verify the widget's container has the data file:
    ls ~/Library/Containers/<your-bundle-id>.widgetkit/Data/widget_data.json
    
  • Check widget logs: log show --last 1m --predicate 'subsystem == "com.tauri.widgets"' --style compact
  • Ensure TauriWidgetExtension.entitlements contains com.apple.security.app-sandbox and the correct App Group.
  • Align Swift widgetId with JS (default "default").

Widget doesn't update

  • Apple limits widget refreshes to ~40–70 per day.
  • Check plugin throttle on iOS (TAURI_WIDGET_MIN_RELOAD_SECS; Debug 0, Release 900). On the macOS app host this env is unused — inspect ApplyOutcome.reload from setWidgetConfig.
  • Prefer { type: "timer" } for live UI.

More symptoms: Troubleshooting index. Transport: Apple data transport.