@capgo/capacitor-app-intents
v8.3.0
Published
Siri, Shortcuts, Spotlight, Home Screen quick actions, and Apple App Intents for Capacitor apps with a JavaScript dispatch bridge.
Readme
@capgo/capacitor-app-intents
Ship Siri phrases, Shortcuts, Spotlight search, Home Screen quick actions, and App Intents entity parameters in Capacitor apps without rebuilding your web layer for every action.
Siri app skills for Capacitor (iOS 27.3 Developer Preview)
Apple's app skills preview lets Siri run multi-step workflows in your app. @capgo/capacitor-app-intents connects that stack to the Capacitor JavaScript layer you already ship:
- App skills in
Skills.skillsbundle: describe how Siri should orchestrate your tools (generated from config asSKILL.md). - Typed tool intents: build-time codegen with parameters, entities, and string results instead of a single generic dispatch intent.
- Real results back to Siri: when
awaitJavaScriptResultis enabled,completeInvocation()/withInvocationCompletion()suspends the nativeperform()until JavaScript returns a value Siri can speak and chain into the next step (iOS 17+ string results; seedocs/app-skills.md).
Honest SDK guards: @AppIntent(.tool) / ToolIntent need the iOS 27.3 SDK (Xcode 27.3 beta). This package does not declare those APIs so CI keeps building on current Xcode. Generated Swift includes a comment; you add the tool trait in app-owned files when your SDK is ready. App skills validation on a real device needs iOS 27.3 beta and Apple Intelligence (not Simulator). The generic CapgoDispatchAppIntent path remains for iOS 16+ apps that do not adopt skills yet.
Minimal setup (config, skill, JavaScript)
app-intents.codegen.json (excerpt):
{
"intents": [
{
"name": "OrderDishToolIntent",
"actionName": "orderDish",
"title": "Order dish",
"tool": true,
"awaitJavaScriptResult": true,
"execution": "javascript",
"parameters": [
{ "name": "dish", "type": "entity", "entityType": "CapgoCatalogEntity" }
],
"result": { "type": "string", "title": "Order summary" }
}
],
"skills": [
{
"name": "order-meal",
"description": "Guides Siri through choosing a dish and placing an order.",
"body": "Use the order dish tool after the person picks an item. Confirm the summary before finishing."
}
]
}Generate native artifacts and add them to your iOS app target (not the plugin package):
node node_modules/@capgo/capacitor-app-intents/scripts/generate-typed-intents.mjs \
--config app-intents.codegen.json \
--output-dir ios/App/App/GeneratedAppIntents
node node_modules/@capgo/capacitor-app-intents/scripts/generate-skills-bundle.mjs \
--config app-intents.codegen.json \
--output ios/App/App/Skills.skillsbundlegenerate-skills-bundle.mjs writes Skills/order-meal/SKILL.md like:
---
name: order-meal
description: "Guides Siri through choosing a dish and placing an order."
---
Use the order dish tool after the person picks an item. Confirm the summary before finishing.Return a tool result from JavaScript:
import { useAppIntentsListener, withInvocationCompletion } from '@capgo/capacitor-app-intents';
await useAppIntentsListener(
withInvocationCompletion(async (invocation) => {
if (invocation.name === 'orderDish') {
return { value: 'Ordered pasta', message: 'Your pasta order is in.' };
}
}),
);Handlers can also call completeInvocation({ id, result, dialog }) directly when you manage the listener yourself.
Why Capgo
- Capacitor-first: same TypeScript handlers you use for Shortcuts, Spotlight, and the pending queue now power Siri tool results.
- Backward compatible: keep
CapgoDispatchAppIntentfor existing shortcuts; adopt typed intents and skills when you are ready. - Live handler updates: business logic in your web bundle can ship through Capgo live updates without an App Store submission for every tweak. Siri phrases, shortcut literals, generated Swift, and
Skills.skillsbundlestill require an iOS rebuild when you change them.
Full steps: docs/app-skills.md.
Built and maintained with AI
We build, improve and fix our plugins with heavy use of AI, so issues usually get fixed in under a day and pull requests get feedback the same day. A human still reviews, tests and merges 50+ pull requests daily.
- Most plugin issues get a fix pull request the same day, often within a couple of hours, and are usually resolved in one to two days.
- Every pull request goes through our AI review system, usually within minutes.
- Our AI pre-checks tests, code review, conventions and security, then a human reviews, tests and merges.
- A human, Martin, reviews, tests and merges 50+ pull requests every day.
- In the last 90 days, 95% of plugin issues were resolved.
Learn more about how we build with AI
Key features
- JavaScript dispatch bridge:
CapgoDispatchAppIntentplusCapgoAppIntentsBridgefor custom Swift intents. - Pending queue: cold start safe storage with
getPendingInvocations(),removePendingInvocation(),appIntentInvoked, cap 100. - Entity catalogs:
setEntityCatalog()powersCapgoCatalogEntityandEntityQueryfor Siri parameters. - Spotlight:
indexSpotlightEntities()usesCSSearchableItemon iOS 16+. On iOS 18+ also donatesIndexedEntitythroughindexAppEntities. - Quick actions:
setHomeScreenShortcutItems()maps toUIApplicationShortcutItem. - Siri phrases: compile time literals only. Use the included codegen script (not JavaScript).
- Siri chaining (iOS 17+):
completeInvocation()/failInvocation()return real tool results to Siri when intents await JavaScript. - App skills (iOS 27.3 preview): generate
Skills.skillsbundlefromSKILL.mdviagenerate-skills-bundle.mjs. Seedocs/app-skills.md. - Platforms: iOS 16 and later. Android and web reject with a clear error.
Compatibility
| Plugin version | Capacitor | Maintained | | -------------- | --------- | ---------- | | v8.x | v8.x | Yes |
Install
bun add @capgo/capacitor-app-intents
bunx cap syncConfiguration
// capacitor.config.ts
plugins: {
CapgoAppIntents: {
appGroupId: 'group.your.app', // optional
spotlightDomainIdentifier: 'your.app.bundle', // optional
},
},Handle invocations
import {
CapgoAppIntents,
drainPendingInvocations,
useAppIntentsListener,
} from '@capgo/capacitor-app-intents';
import { withInvocationCompletion } from '@capgo/capacitor-app-intents';
const handleInvocation = withInvocationCompletion(async (invocation) => {
console.log(invocation.name, invocation.params);
return { value: `Handled ${invocation.name}` };
});
await useAppIntentsListener(handleInvocation);
// Or manually: register the listener before draining pending items.
const listener = await CapgoAppIntents.addListener('appIntentInvoked', async (event) => {
await handleInvocation(event.invocation);
});
await drainPendingInvocations(handleInvocation);Siri phrases and shortcut icons (codegen)
AppShortcut phrases and systemImageName values must be compile time literals in Swift. JavaScript cannot change them at runtime.
- Copy
app-shortcuts.config.example.jsontoapp-shortcuts.config.jsonin your app repo. - Edit
actionName,shortTitle,systemImageName, andphrases({{applicationName}}maps to\(.applicationName)). - Generate Swift and add it to your iOS app target:
node node_modules/@capgo/capacitor-app-intents/scripts/generate-app-shortcuts.mjs \
--config app-shortcuts.config.json \
--output ios/App/App/CapgoGeneratedAppShortcuts.swiftAdd the generated file to your iOS App target (not the plugin package). Link the plugin SPM package to the app so CapgoDispatchAppIntent resolves.
On Capacitor 8, forward SceneDelegate quick actions and continued Spotlight activities using CapgoAppIntentsLifecycle. See docs/ios-scene-integration.md.
- Rebuild the iOS app. Siri and Shortcuts read the generated
AppShortcutsProvider.
Typed tool intents and app skills
Use app-intents.codegen.example.json for typed parameters, results, and SKILL.md skills.
node node_modules/@capgo/capacitor-app-intents/scripts/generate-typed-intents.mjs \
--config app-intents.codegen.json \
--output-dir ios/App/App/GeneratedAppIntents
node node_modules/@capgo/capacitor-app-intents/scripts/generate-skills-bundle.mjs \
--config app-intents.codegen.json \
--output ios/App/App/Skills.skillsbundleThe generic CapgoDispatchAppIntent(actionName:) shortcut path remains available. Typed intents call CapgoIntentPerformExecutor and can await JavaScript.
iOS 16 vs iOS 17 shortcuts (mixed config): Dispatch shortcuts (CapgoDispatchAppIntent) work on iOS 16+. Shortcuts that target typed intents with awaitJavaScriptResult: true need iOS 17+ at runtime. Apple allows only one AppShortcutsProvider per app, and Xcode 26 rejects if #available inside @AppShortcutsBuilder. By default (minimumIOSVersion omitted or 16), a mixed codegen JSON gets a single @available(iOS 16.0, *) provider with only dispatch shortcuts. Tool shortcut Siri phrases are omitted (CLI warning plus #warning in generated Swift). Typed AppIntent types are still generated for the Shortcuts app. To emit all shortcuts on one @available(iOS 17.0, *) provider, set "minimumIOSVersion": 17 in app-intents.codegen.json (the generator does not read the Xcode deployment target). Your app must still target iOS 17+ at build time for that layout. Or keep the default and add a CapgoDispatchAppIntent shortcut entry for the Siri phrase you need on iOS 16+.
Custom intents can still call CapgoAppIntentsBridge.shared.enqueue(...) from Swift. See docs/ExampleCustomIntent.swift. See docs/app-skills.md for Siri AI preview evaluation on a real device.
Entity catalog
await CapgoAppIntents.setEntityCatalog({
type: 'dish',
entries: [{ id: 'pasta', title: 'Pasta' }],
});Spotlight
await CapgoAppIntents.indexSpotlightEntities({
entities: [
{
id: 'dish-pasta',
title: 'Pasta',
actionName: 'openDish',
params: { dishId: 'pasta' },
},
],
});On iOS 18 and later the plugin also indexes CapgoSpotlightIndexedEntity for semantic search.
Home Screen quick actions
await CapgoAppIntents.setHomeScreenShortcutItems({
items: [
{
type: 'lastOrder',
title: 'Last order',
iconName: 'clock',
params: { screen: 'orders' },
},
],
});Apple schema (alpha, JavaScript queue only)
performAppleSchemaTemplate({ template: 'mail_create_draft', params }) does not open Mail or call Apple Mail schema APIs. Third party apps do not get a supported native Mail draft App Intent API.
The plugin only enqueues a pending invocation named appleSchemaMailCreateDraft so your JavaScript can implement compose UI or deep links.
Example app
npm run example:build
cd example-app
bunx cap sync iosSee example-app/README.md for a committed iOS project with generated shortcuts, typed intents, and Skills.skillsbundle already in the App target.
Docs
docs/app-intents.mddocs/ExampleCustomIntent.swift
API
getPendingInvocations()removePendingInvocation(...)completeInvocation(...)failInvocation(...)setOnscreenEntityContext(...)clearOnscreenEntityContext()setEntityCatalog(...)setHomeScreenShortcutItems(...)indexSpotlightEntities(...)removeSpotlightEntities(...)performAppleSchemaTemplate(...)addListener('appIntentInvoked', ...)removeAllListeners()getPluginVersion()- Interfaces
- Type Aliases
Capgo App Intents plugin interface.
Bridges Swift App Intents, Siri, Shortcuts, Spotlight, and Home Screen quick actions to JavaScript with a durable pending queue for cold starts.
iOS 16 and later. Android and web reject calls with a clear unimplemented error.
getPendingInvocations()
getPendingInvocations() => Promise<{ invocations: AppIntentInvocation[]; }>Return invocations queued before JavaScript was ready.
Returns: Promise<{ invocations: AppIntentInvocation[]; }>
Since: 0.1.0
removePendingInvocation(...)
removePendingInvocation(options: { id: string; }) => Promise<void>Remove one pending invocation after your handler processes it.
| Param | Type |
| ------------- | ---------------------------- |
| options | { id: string; } |
Since: 0.1.0
completeInvocation(...)
completeInvocation(options: { id: string; result: AppIntentInvocationResult; dialog?: string; }) => Promise<void>Resolve an invocation that is awaiting a JavaScript result for Siri.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| options | { id: string; result: AppIntentInvocationResult; dialog?: string; } |
Since: 8.2.0
failInvocation(...)
failInvocation(options: { id: string; error: string; }) => Promise<void>Fail an invocation that is awaiting a JavaScript result.
| Param | Type |
| ------------- | ------------------------------------------- |
| options | { id: string; error: string; } |
Since: 8.2.0
setOnscreenEntityContext(...)
setOnscreenEntityContext(options: { entities: OnscreenEntityReference[]; }) => Promise<void>Publish optional on-screen entity context for catalog queries.
| Param | Type |
| ------------- | ----------------------------------------------------- |
| options | { entities: OnscreenEntityReference[]; } |
Since: 8.2.0
clearOnscreenEntityContext()
clearOnscreenEntityContext() => Promise<void>Clear on-screen entity hints when your UI no longer shows those rows.
Since: 8.2.0
setEntityCatalog(...)
setEntityCatalog(options: { type: string; entries: EntityCatalogEntry[]; }) => Promise<void>Persist an entity catalog for a given type string.
Powers Siri and Shortcuts entity parameters without new Swift per row.
| Param | Type |
| ------------- | ------------------------------------------------------------- |
| options | { type: string; entries: EntityCatalogEntry[]; } |
Since: 0.1.0
setHomeScreenShortcutItems(...)
setHomeScreenShortcutItems(options: { items: HomeScreenShortcutItem[]; }) => Promise<void>Replace Home Screen quick actions (UIApplicationShortcutItems).
| Param | Type |
| ------------- | ------------------------------------------------- |
| options | { items: HomeScreenShortcutItem[]; } |
Since: 0.1.0
indexSpotlightEntities(...)
indexSpotlightEntities(options: { entities: SpotlightEntity[]; }) => Promise<void>Index Spotlight items for your app domain.
Uses CSSearchableItem on iOS 16 and later. On iOS 18 and later also donates
IndexedEntity values through indexAppEntities and associateAppEntity.
| Param | Type |
| ------------- | --------------------------------------------- |
| options | { entities: SpotlightEntity[]; } |
Since: 0.1.0
removeSpotlightEntities(...)
removeSpotlightEntities(options: { ids: string[]; }) => Promise<void>Remove Spotlight items by id.
| Param | Type |
| ------------- | ------------------------------- |
| options | { ids: string[]; } |
Since: 0.1.0
performAppleSchemaTemplate(...)
performAppleSchemaTemplate(options: { template: AppleSchemaTemplate; params: Record<string, unknown>; }) => Promise<{ queuedInvocationId?: string; }>Queue a JavaScript handler for an alpha Apple schema template.
This does not call private Mail or system schema APIs. It only enqueues an
invocation (for example appleSchemaMailCreateDraft) for your app code to handle.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| options | { template: 'mail_create_draft'; params: Record<string, unknown>; } |
Returns: Promise<{ queuedInvocationId?: string; }>
Since: 0.1.0
addListener('appIntentInvoked', ...)
addListener(eventName: 'appIntentInvoked', listenerFunc: (event: AppIntentInvokedEvent) => void) => Promise<PluginListenerHandle>Listen for appIntentInvoked when a new invocation is queued.
| Param | Type |
| ------------------ | ------------------------------------------------------------------------------------------- |
| eventName | 'appIntentInvoked' |
| listenerFunc | (event: AppIntentInvokedEvent) => void |
Returns: Promise<PluginListenerHandle>
Since: 0.1.0
removeAllListeners()
removeAllListeners() => Promise<void>Remove all listeners for this plugin.
Since: 0.1.0
getPluginVersion()
getPluginVersion() => Promise<{ version: string; }>Native plugin version string.
Returns: Promise<{ version: string; }>
Since: 0.1.0
Interfaces
AppIntentInvocation
| Prop | Type | Description | Since |
| -------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----- |
| id | string | Stable id for this queued invocation. | 0.1.0 |
| name | string | Handler name your JavaScript listens for. | 0.1.0 |
| params | Record<string, unknown> | Parameters passed from Siri, Shortcuts, Spotlight, or quick actions. | 0.1.0 |
| source | AppIntentInvocationSource | Origin of the invocation. | 0.1.0 |
| createdAt | number | Unix timestamp in milliseconds when the invocation was queued. | 0.1.0 |
| awaitingResult | boolean | When true, the native side is waiting for completeInvocation or failInvocation. | 8.2.0 |
AppIntentInvocationResult
Result payload returned to Siri after JavaScript completes an awaiting invocation.
Typed codegen intents on iOS 17+ surface value and optional message/summary as a
ReturnsValue<String> string to Siri. The generic CapgoDispatchAppIntent path still
completes JavaScript but does not return that string to Siri on iOS 16.
| Prop | Type | Description | Since |
| ------------- | ------------------- | ---------------------------------------------- | ----- |
| value | string | Primary string Siri can speak or chain on. | 8.2.0 |
| message | string | Optional dialog Siri speaks to the user. | 8.2.0 |
| summary | string | Optional summary used when value is omitted. | 8.2.0 |
OnscreenEntityReference
Optional on-screen entity hint for Siri disambiguation.
This complements native SwiftUI entity annotations. Use it from JavaScript when your web UI shows catalog items Siri should prefer.
| Prop | Type |
| ----------------- | ------------------- |
| catalogType | string |
| entityId | string |
| title | string |
EntityCatalogEntry
One row in a runtime entity catalog used by Siri and Shortcuts parameters.
| Prop | Type | Description | Since |
| -------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------- | ----- |
| id | string | Unique id within the catalog type. | 0.1.0 |
| title | string | Primary label shown in Shortcuts and Siri. | 0.1.0 |
| subtitle | string | Optional subtitle. | 0.1.0 |
| metadata | Record<string, unknown> | Optional extra metadata forwarded to JavaScript when the entity is chosen. | 0.1.0 |
HomeScreenShortcutItem
Home Screen quick action item.
| Prop | Type | Description | Since |
| -------------- | ---------------------------------------------------------------- | ------------------------------------------- | ----- |
| type | string | Stable type string delivered to JavaScript. | 0.1.0 |
| title | string | Visible title under the icon. | 0.1.0 |
| subtitle | string | Optional subtitle. | 0.1.0 |
| iconName | string | Optional SF Symbol name. | 0.1.0 |
| params | Record<string, unknown> | Optional params merged into the invocation. | 0.1.0 |
SpotlightEntity
Spotlight searchable entity.
Indexed on iOS 16 with Core Spotlight. On iOS 18 and later the plugin also
donates an IndexedEntity for semantic Spotlight search.
| Prop | Type | Description | Since |
| ----------------- | ---------------------------------------------------------------- | ------------------------------------------------ | ----- |
| id | string | Unique id within your app domain. | 0.1.0 |
| title | string | Title shown in Spotlight. | 0.1.0 |
| description | string | Optional description. | 0.1.0 |
| keywords | string[] | Optional keywords. | 0.1.0 |
| actionName | string | Action name delivered when the result is opened. | 0.1.0 |
| params | Record<string, unknown> | Optional params merged into the invocation. | 0.1.0 |
PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |
AppIntentInvokedEvent
| Prop | Type | Description | Since |
| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- | ----- |
| invocation | AppIntentInvocation | The invocation that was just queued or replayed to listeners. | 0.1.0 |
Type Aliases
Record
Construct a type with a set of properties K of type T
{ [P in K]: T; }
AppIntentInvocationSource
Where an invocation originated.
'app_intent' | 'spotlight' | 'quick_action' | 'apple_schema'
AppleSchemaTemplate
Alpha Apple schema template identifiers shipped by the plugin.
'mail_create_draft'
License
MPL-2.0
