capacitor-app-intents

App Intents for Capacitor Apps

Add native App Intents to the iOS project so system surfaces can run app actions, and connect them to the web layer. App Intents are Swift only. There is no JavaScript API for them, so every intent is native code in the App target or an extension, and the web layer is reached through a URL or a small local plugin.

When to Use

TRIGGER when:

• The user wants Siri phrases, Shortcuts actions, App Shortcuts, Spotlight actions, Action button or Apple Intelligence integration for a Capacitor app
• The user wants a widget button or a Control Center control to run an app action
• An intent opens the app, but the web view does not navigate, or it navigates only on warm launch
• A background intent crashes, times out, or tries to call JS
• Migrating openAppWhenRun to supportedModes, or adopting iOS 26/27 App Intents APIs
• A plugin author wants to ship App Intents with a plugin

Do not use:

• Universal Links / custom scheme / appUrlOpen setup: capacitor-deep-linking
• AppDelegate to SceneDelegate migration: capacitor-uiscene-migration
• Push notification actions: capacitor-push-notifications
• Live Activities or SVG widgets driven from JS: capacitor-plugins (@capgo/capacitor-widget-kit)
• Android app shortcuts and intents: not covered here

Facts that drive the design

• App Intents need iOS 16. Capacitor 8 deploys to iOS 15, so every intent type, entity, query and AppShortcutsProvider needs @available(iOS 16.0, *), or the user raises the deployment target. Capacitor 9 deploys to iOS 16, so the base API needs no gating. Newer APIs still do (tables in references/ios-26-27-apis.md).
• A background intent has no WebView. iOS can launch the app process headless for .background intents. AppDelegate.application(_:didFinishLaunchingWithOptions:) runs, but no scene connects and CAPBridgeViewController never loads. Background intents must do native work only (network, storage, HealthKit, etc.). They cannot call JS or plugins through the bridge.
• perform() is not on the main actor, and it can run more than once. Hop explicitly (await MainActor.run or @MainActor func perform()) before you touch UIKit, the bridge or @MainActor state. Do irreversible work last. Details: references/intent-traps.md.
• With UIScene (Capacitor 8.5+) URL delivery moved. Universal Links and custom-scheme opens reach SceneDelegate and are forwarded by SceneDelegateProxy, which posts the notifications @capacitor/app listens to. If the app still has custom URL code in AppDelegate, it no longer runs. Check capacitor-deep-linking first if appUrlOpen does not fire for a normal link. An intent cannot fix a broken link pipeline.
• On cold launch the JS listener does not exist yet. Any route an intent hands to the web layer must survive until JS asks for it: use App.getLaunchUrl() for URLs, or a pending-route store plus notifyListeners(..., retainUntilConsumed: true) for the local-plugin path.
• Identifiers are a public contract. Intent type names, AppEntity.id values, AppEnum raw values, URL formats and shipped phrases are stored in users' saved shortcuts. Add new ones; do not rename or remove shipped ones without telling the user.