Terminal
Terminal/Skill
Audits an iOS Capacitor app or plugin for the 8.5 UIScene lifecycle change and merges the needed SceneDelegate and Info.plist edits.
By Ionic
Works with
npx skills add ionic-team/capacitor-skills --skill capacitor-uiscene-migratorGuides a Capacitor 8.4 → 8.5 iOS migration to the UIScene lifecycle. The
CLI migrator (npx cap migrate) handles projects that still match the
Capacitor templates; this skill exists for everything else. It audits
before editing, asks the developer where judgement is required, merges
into existing files rather than replacing them, and delegates the
mechanical work to the CLI whenever the project shape allows.
The canonical migration reference is the 8.4 → 8.5 migration guide. Link it whenever a step is left for the developer to do manually.
npx cap migrate reported a partial state and skippedSceneDelegate.swift or a customized
AppDelegate.swift (deep-link routing, third-party SDK forwarding)cordova-plugin-migratorcapacitor-plugin-generatorios/ platform or
iOS sources@capacitor/cli 8.5+ available for the npx cap migrate handoffThese determine what breaks and what does not. Do not soften them.
UIApplicationSceneManifest
keeps the AppDelegate path, which still works on the 8.5 core. iOS
posts UIScene.* notifications even for legacy apps (compatibility
scene), so the bridge's JS resume/pause events fire in both modes.application(_:open:options:), application(_:continue:), and the
four foreground/background AppDelegate methods
(applicationDidBecomeActive, applicationWillResignActive,
applicationDidEnterBackground, applicationWillEnterForeground).
Custom code in any of those silently stops running. The
UIApplication notifications still fire; didFinishLaunching,
applicationWillTerminate, push token registration, and the
remote-notification callbacks stay on the AppDelegate.SceneDelegateProxy re-posts the legacy .capacitorOpenURL,
.capacitorOpenUniversalLink, and CDVPluginHandleOpenURL
notifications with the same payload shape, so existing observers keep
working. Cold-start URLs are delivered after the bridge view appears,
so both appUrlOpen and getLaunchUrl() work on cold launch..capacitorSceneWillConnect, .capacitorSceneOpenURL, and
.capacitorSceneOpenUniversalLink notifications carry the UIScene
as the object. They are only posted on 8.5+; plugins that also support
8.4 must keep using the legacy names.TmpViewController and CapacitorBridge.tmpWindow were removed. Any
reference is a build error on 8.5.scene(_:willConnectTo:); Main.storyboard no longer provides the
root view controller. Custom CAPBridgeViewController subclasses are
instantiated in the SceneDelegate, not set in the storyboard.SceneDelegate.swift, AppDelegate.swift,
or Info.plist structure. Merge surgically per
references/surgical-merges.md.npx cap migrate instead of editing files by hand.AskUserQuestion where available; otherwise ask in plain text and
wait.Info.plist, AppDelegate.swift, or
project files. The plugin branch is audit and advice only.Decide app vs. plugin before anything else.
ios/App/App.xcodeproj (or capacitor.config.* with an
ios/ platform directory).Package.swift or .podspec depending on
Capacitor, CAPPlugin/CapacitorPlugin subclasses in ios/Sources
or ios/Plugin, and no App/App.xcodeproj.Plugin repo → skip to Phase 10 (references/plugin-repo-audit.md).
ios/App/Podfile → CocoaPods; Package.swift or an SPM
reference inside the Xcode project → SPM. This affects how npx cap sync ios behaves, not the SceneDelegate content: the 8.5 templates
ship one SceneDelegate for both.@capacitor/ios version in package.json. If below 8.5, the
dependency update is part of the migration; the CLI migrator handles
it, or update manually per the guide.Read the same three signals the CLI migrator uses:
Info.plist contains UIApplicationSceneManifestSceneDelegate.swift exists on disk in the app target directory
(pbxproj registration is a separate concern, handled in Phase 7)AppDelegate.swift contains UISceneConfiguration(name:| Signals present | State | Route |
|---|---|---|
| 0 of 3 | eligible | Phases 4-6, then Phase 7a: hand off to npx cap migrate |
| 3 of 3 | already migrated | Audit only (Phase 4), then verify (Phase 9) |
| 1-2 of 3 | partial | Phases 4-6, then Phase 7b: surgical merges |
Every route audits before anything runs or changes; the routes differ only in who applies the changes.
The CLI warns and skips on partial states by design. Partial is exactly where this skill does its own editing.
Run the scans in
references/audit-patterns.md across the
app's iOS sources and installed plugins (node_modules/@capacitor*,
plus any local plugin paths). Collect findings for:
UIApplication.shared.applicationState usageapplication(_:open:) / application(_:continue:) bodies
beyond the ApplicationDelegateProxy forwarderSceneDelegate.swift implementations and what they containtmpWindow / TmpViewController (build errors on 8.5)UIApplicationSceneManifest entries.capacitorOpenURL / .capacitorOpenUniversalLink observers
(informational: they keep working)Report every finding with file and line before touching anything. Group as: blocks the build (tmpWindow/TmpViewController), needs a decision (custom delegate bodies, existing SceneDelegate), informational (observers, applicationState in plugins the developer does not own). Ask the developer to confirm proceeding.
Ask, at minimum:
application(_:open:options:) / application(_:continue:) in
AppDelegate.swift? They become dead code under scenes. Keeping them
is harmless; removing them is cleaner. If the body contains custom
logic, it must move to the SceneDelegate either way. On the eligible
route, apply the answer after the CLI has run.application(_:open:) body: migrate it manually (the
developer moves the logic) or have the skill move it into
scene(_:openURLContexts:) alongside the proxy forwarder? Show the
body before asking. Skip this question when the body is
forwarder-only per the audit test.Verify the resolved CLI first: run npm install if node_modules is
missing, then npx cap --version; the UIScene migrator needs 8.5 or
newer. Then run npx cap migrate and interpret its output. It writes
SceneDelegate.swift, patches Info.plist and AppDelegate.swift,
registers the file in project.pbxproj, warns on the scan patterns from
Phase 4, and links the migration guide. Confirm each step's log line;
if the CLI skipped a step (file existed, partial state raced in),
fall through to Phase 7b for that step only.
Apply only the missing pieces, per references/surgical-merges.md:
UIApplicationSceneManifest into
Info.plist, preserving existing keysconfigurationForConnecting → insert into the existing
AppDelegate.swift before the class's closing brace, displacing
nothingSceneDelegate.swift → create from
references/scene-delegate-template.md,
or add the missing SceneDelegateProxy.shared forwarders to the
existing one, preserving all custom logicproject.pbxproj (Xcode does this when the
file is added through the IDE; otherwise follow the reference)Run npx cap sync ios. If Xcode is available, build the app target and
surface any errors (most commonly leftover tmpWindow references).
Walk the developer through, linking the guide for detail:
resume/pause fire (they are
scoped to the app's scene now)appUrlOpen listener and App.getLaunchUrl())No app-level files to patch. Audit the plugin's Swift per references/plugin-repo-audit.md and report: lifecycle assumptions that break under scenes, APIs removed in 8.5, and the compatibility rules for supporting 8.4 and 8.5 with one plugin version. Apply code changes only if the developer asks, and only in the plugin's own sources.
node_modules (report it;
the fix belongs upstream)npx cap migrate warns "partial state" → expected; this skill's
Phase 7b exists for that. Do not reset the project without asking.project.pbxproj edits fail or the project no longer opens → revert
the pbxproj change and register the file through Xcode instead.tmpWindow / TmpViewController → the references
must be deleted; there is no 8.5 replacement (the bridge's
viewController is the presentation anchor).SceneDelegate exists but the app shows a black screen → the
delegate neither creates a window nor lets a storyboard do it; add
the window setup from the template.cordova-plugin-migrator: Cordova plugin to Capacitor migrationcapacitor-plugin-generator: new Capacitor plugin scaffolds| File | Purpose |
|---|---|
| references/scene-delegate-template.md | The 8.5 SceneDelegate template and custom-subclass variant |
| references/audit-patterns.md | Exact scan patterns with commands |
| references/surgical-merges.md | Merge recipes for partial and hand-rolled projects |
| references/plugin-repo-audit.md | Plugin-author branch: audit and compatibility rules |