# Project Setup for App Intents in a Capacitor App

## Where files go

```
ios/App/App/
  AppDelegate.swift
  SceneDelegate.swift            # Capacitor 8.5+
  Intents/
    AppShortcuts.swift           # one AppShortcutsProvider per app
    OpenSectionIntent.swift      # foreground intents
    SyncNowIntent.swift          # background intents
    Entities/NoteEntity.swift    # AppEntity + EntityQuery
  AppIntentsBridge.swift         # local plugin (if used), see web-bridge.md
  MainViewController.swift       # CAPBridgeViewController subclass that registers it
```

- Create the files in Xcode (File > New > File, Swift File, App group) so they get the **App** target membership. If you write files from the CLI, add them to the target: a `PBXFileReference`, a `PBXBuildFile`, an entry in the `App` group and one in the App target's Sources build phase. Xcode 16+ projects that use folder references ("synchronized groups") pick up new files automatically. Check which kind the project uses before you edit `project.pbxproj`.
- `npx cap sync` does not touch these files. They are app-owned like `AppDelegate.swift`.
- Do not put intents in `ios/App/CapApp-SPM/` (regenerated) or in `Pods/`.

## One AppShortcutsProvider per app

Put exactly one `AppShortcutsProvider` in the App target. App Shortcuts declared in a plugin's framework are not picked up the same way. A plugin that wants to contribute intents should ship the intent types and document the `AppShortcut` entries the app adds to its own provider. Check current Apple docs on `AppIntentsPackage` before you design a plugin that ships intents from a framework or Swift package.

## Extensions

Widgets and controls live in a Widget Extension target (File > New > Target > Widget Extension). Then:

- Give every intent file used by both the app and the widget **both** target memberships (App and the extension), or move the shared types into a framework.
- Code compiled into the extension cannot import `Capacitor`, use `UIApplication.shared`, or reach the WebView. Keep shared intent code free of Capacitor imports. Put bridge calls behind `#if` or in app-only files.
- Set the extension's deployment target and Swift version deliberately. Widgets need iOS 14+, interactive widgets with `Button(intent:)` iOS 17+, controls iOS 18+.

## App Groups (shared data between app, extension and intents)

1. Signing & Capabilities > + Capability > App Groups on the App target and each extension. Use the same `group.<bundle-id>...` identifier.
2. Read and write through `UserDefaults(suiteName: "group....")` or the group container URL (`FileManager.default.containerURL(forSecurityApplicationGroupIdentifier:)`).
3. `@capacitor/preferences` writes to `UserDefaults.standard` (keys prefixed by its group, `CapacitorStorage.` by default; check the installed version's source). An intent running **in the app process** can read those keys. An **extension** cannot. Use the App Group suite for anything an extension needs, and expose it to JS through the local plugin.

## Availability gating

| Capacitor | iOS deployment target | Gate needed for base App Intents |
|---|---|---|
| 8.x | 15.0 | Yes: `@available(iOS 16.0, *)` on every type |
| 9.x | 16.0 | No |

```swift
import AppIntents

@available(iOS 16.0, *)
struct OpenInboxIntent: AppIntent { /* ... */ }

@available(iOS 16.0, *)
struct AppShortcuts: AppShortcutsProvider { /* ... */ }
```

Gate code that references intents from iOS 15-reachable code (for example a donation call in a plugin method) with `if #available(iOS 16.0, *)`.

Tag every newer API with its own floor: `OpenURLIntent` and URL-representable types iOS 18, `IndexedEntity` iOS 18, `ControlConfigurationIntent` iOS 18, `supportedModes` iOS 26, `LongRunningIntent` iOS 27. Full table: [ios-26-27-apis.md](ios-26-27-apis.md).

## Registering dependencies

The equivalent of SwiftUI's `App.init()` in a Capacitor app is `AppDelegate.application(_:didFinishLaunchingWithOptions:)`. It runs on every process launch, including headless launches for background intents. `SceneDelegate` and the bridge view controller do not run on headless launches.

```swift
func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    if #available(iOS 16.0, *) {
        AppDependencyManager.shared.add(dependency: NotesStore.shared)
    }
    return true
}
```

## Build checks

```bash
npx cap sync ios
xcodebuild -project ios/App/App.xcodeproj -scheme App \
  -destination 'generic/platform=iOS Simulator' build 2>&1 | grep -iE 'appintents|App Shortcut|phrase|error' | head -40
```

The App Intents metadata is extracted at build time. Warnings about phrases or the App Shortcut count show up there.