fix(ios): adopt UIScene life cycle in default iOS app templates#8527
Open
nilspep wants to merge 1 commit into
Open
fix(ios): adopt UIScene life cycle in default iOS app templates#8527nilspep wants to merge 1 commit into
nilspep wants to merge 1 commit into
Conversation
Apple's TN3187 states that starting with the next major iOS release following iOS 26, apps built with the latest SDK will fail to launch if they don't adopt the UIScene-based life cycle. Both default iOS templates (ios-spm-template and ios-pods-template) still use the pre-scene AppDelegate-only life cycle, so any app scaffolded today via `npx cap add ios` will fail to launch on that SDK with no crash log (UIKit logs: "UIScene life cycle is required for apps built with this SDK") -- the app process starts, immediately shows a black screen, and returns to the Home Screen. This adds the minimal, Apple-documented fix to both templates: - SceneDelegate.swift implementing UIWindowSceneDelegate - AppDelegate: configurationForConnecting / didDiscardSceneSessions - Info.plist: UIApplicationSceneManifest, matching Apple's current official example verbatim (same keys/config name/delegate class) - project.pbxproj: register SceneDelegate.swift in the App target Since the app's root view controller (CAPBridgeViewController) loads from Main.storyboard, the system auto-configures the scene window from UISceneStoryboardFile, so no manual window setup is needed in SceneDelegate. Verified end-to-end on a real device (rebuilt, installed, and launched an app using this exact template layout) -- confirmed this resolves a silent launch failure with zero crash log. Ref: https://developer.apple.com/documentation/technotes/tn3187-migrating-to-the-uikit-scene-based-life-cycle Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Apple's TN3187 – Migrating to the UIKit scene-based life cycle states:
Both default iOS app templates used by the CLI (
ios-spm-templateandios-pods-template) currently only implement the legacyAppDelegate-only life cycle, with noSceneDelegateand noUIApplicationSceneManifestinInfo.plist.Impact: any app scaffolded today via
npx cap add ios(or--packagemanager CocoaPods) will fail to launch when built against that newer SDK. There is no crash and no crash log — the process starts, the screen goes black, and the OS silently returns to the Home Screen. This is very hard to diagnose without knowing to look for this specific runtime issue in the Xcode console (UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption).I hit exactly this while testing a Capacitor app on a real device on a newer iOS SDK, and confirmed the fix against Apple's official (and recently revised) documentation before proposing it here.
Fix
Minimal changes to both templates, following Apple's documented migration path 1:1:
SceneDelegate.swift(new): implementsUIWindowSceneDelegatewith the standard lifecycle stubs. Since the app's root view controller (CAPBridgeViewController) is loaded fromMain.storyboard, the system auto-configures the scene's window fromUISceneStoryboardFile— no manualUIWindowsetup is required.AppDelegate.swift: addsapplication(_:configurationForConnecting:options:)andapplication(_:didDiscardSceneSessions:).Info.plist: addsUIApplicationSceneManifestwithUIApplicationSupportsMultipleScenes = falseand a singleUIWindowSceneSessionRoleApplicationconfiguration pointing atSceneDelegateand the existingMainstoryboard — this matches Apple's current official example verbatim (same keys, sameUISceneConfigurationName/UISceneDelegateClassNamepattern).project.pbxproj: registersSceneDelegate.swiftin theApptarget (file reference, build file, group, Sources build phase).UIMainStoryboardFile/UILaunchStoryboardNameare left untouched — they remain valid and are simply superseded for windowing purposes by the scene manifest, matching Apple's guidance for storyboard-based apps.Verification
Info.plistandproject.pbxprojvalidated withplutil -lint(both templates).xcodebuild, and verified on a physical device: without the fix the app silently fails to launch (black screen, no crash log); with the fix it launches and runs normally.Info.plistsnippet andSceneDelegatepattern against Apple's official TN3187 example to ensure an exact match (not just "a" fix, but the documented fix).Notes for reviewers
mainperCONTRIBUTING.md.npm installrun against the full monorepo tooling in this environment, so I wasn't able to run the repo's own SwiftLint config end-to-end; I did install SwiftLint locally and manually reviewed the new/changed Swift files against the existing file style (4-space indentation, matching comment style, no trailing whitespace, no force-unwraps). Happy to address any CI lint findings.AppDelegate.configurationForConnectingmethod dropped since it's technically redundant onceInfo.plistfully specifies the scene manifest — I kept it since Apple's own template ships it too and it's harmless, but I'm happy to simplify if preferred.