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.appto/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 usingTauriWidgetProvider(widgetId: "default")project.yml— XcodeGen spec for the.appexbuild-widget.sh— builds and signs the.appex; regenerates both.entitlementsfrom 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:
- Rust + frontend build
build-widget.sh→ signed.appex- Tauri copies PlugIns, nested-codesigns, notarizes (if configured), writes
.app/ DMG
Tip:
{ "scripts": { "build:macos": "tauri build" } }thenpnpm build:macos.
Code Signing
build-widget.sh signs the .appex before bundling. Identity resolution:
WIDGET_SIGN_IDENTITYAPPLE_SIGNING_IDENTITY- Fallback:
-(ad-hoc)
npx tauri-widgets signing # lists identities
security find-identity -v -p codesigning
| Signing | Widget visible | transport | Distribution |
|---|---|---|---|
Ad-hoc (-) | Yes | widgetContainer (default) | Local only |
| Developer ID (+ notarization) | Yes | widgetContainer (default) | Direct distribution |
| Mac App Store (sandboxed host) | Yes | appGroup | App 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 agroup.*container without a provisioning profile).- Check that the app is not sandboxed (
App.entitlementsshould not containcom.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.entitlementscontainscom.apple.security.app-sandboxand the correct App Group. - Align Swift
widgetIdwith 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; Debug0, Release900). On the macOS app host this env is unused — inspectApplyOutcome.reloadfromsetWidgetConfig. - Prefer
{ type: "timer" }for live UI.
More symptoms: Troubleshooting index. Transport: Apple data transport.