feat: Implement UIScene lifecycle for iOS

[Srishtyshree]

feat: Implement UIScene lifecycle for iOS

Summary

This PR implements UIScene lifecycle support for React Native on iOS, resolving the warning: CLIENT OF UIKIT REQUIRES UPDATE: This process does not adopt UIScene lifecycle. This will become an assert in a future version.

Fixes #54739

Problem

Starting with iOS 13, Apple introduced the UIScene lifecycle to support multi-window applications and better separate UI concerns from application-level concerns. React Native's RCTAppDelegate currently doesn't support this modern lifecycle, causing a warning that Apple has indicated will eventually become an assertion (app crash) in future iOS versions.

Solution

This PR adds UIScene lifecycle support to RCTAppDelegate while maintaining backward compatibility:

Changes Made

1. Modified RCTAppDelegate.h

• Added application:configurationForConnectingSceneSession:options: method declaration
• Method is marked with API_AVAILABLE(ios(13.0)) for backward compatibility

2. Modified RCTAppDelegate.mm

• Implemented UIScene configuration method
• Returns a UISceneConfiguration that specifies RCTSceneDelegate as the scene delegate class

3. Created RCTSceneDelegate.h

• New scene delegate class conforming to UIWindowSceneDelegate
• Marked with API_AVAILABLE(ios(13.0))
• Manages the window property for the scene

4. Created RCTSceneDelegate.mm

• Implements UIScene lifecycle methods:
  • scene:willConnectToSession:options: - Sets up the window and React Native root view
  • sceneDidDisconnect: - Handles scene disconnection
  • sceneDidBecomeActive: - Scene activation handling
  • sceneWillResignActive: - Scene deactivation handling
  • sceneWillEnterForeground: - Foreground transition
  • sceneDidEnterBackground: - Background transition
• Integrates with existing RCTAppDelegate to access RCTReactNativeFactory and RCTRootViewFactory

5. Updated RNTester/Info.plist

• Added UIApplicationSceneManifest configuration
• Demonstrates proper UIScene setup for React Native apps

Key Design Decisions

1. Backward Compatibility: All UIScene-related code is guarded with API_AVAILABLE(ios(13.0)), ensuring apps targeting iOS < 13 continue to work.

2. Opt-in Approach: UIScene support is activated only when apps include the UIApplicationSceneManifest in their Info.plist. Existing apps without this configuration continue using the traditional app delegate lifecycle.

3. Integration with Existing Architecture: The RCTSceneDelegate accesses the app delegate to retrieve the RCTReactNativeFactory, maintaining consistency with the existing React Native initialization flow.

4. No Breaking Changes: Existing apps using RCTAppDelegate without UIScene configuration will continue to work exactly as before.

Testing

Manual Testing Performed

1. ✅ RNTester with UIScene: Built and ran RNTester with UIScene manifest - app launches successfully, no warnings
2. ✅ Backward Compatibility: Verified that removing UIScene manifest still works (traditional lifecycle)
3. ✅ Scene Lifecycle Events: Tested app backgrounding, foregrounding, and scene transitions

Expected Behavior

Before this PR:

• Warning in Xcode console: CLIENT OF UIKIT REQUIRES UPDATE: This process does not adopt UIScene lifecycle

After this PR:

• No warning when UIApplicationSceneManifest is present in Info.plist
• App properly adopts UIScene lifecycle on iOS 13+
• Existing apps without UIScene manifest continue working as before

Migration Guide for Users

For New Apps

Include the following in your Info.plist:

<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <false/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>UIWindowSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>Default Configuration</string>
                <key>UISceneDelegateClassName</key>
                <string>RCTSceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

For Existing Apps

Option 1: Adopt UIScene (Recommended for iOS 13+)

• Add the UIApplicationSceneManifest configuration above to your Info.plist
• No code changes required if using RCTAppDelegate

Option 2: Continue with Traditional Lifecycle

• No changes needed
• App will continue working as before
• Warning will persist but can be ignored for now

Changelog

[iOS] [Added] - Implement UIScene lifecycle support for iOS 13+

Additional Notes

• The RCTAppDelegate class is marked as deprecated in favor of RCTReactNativeFactory, but this PR adds UIScene support to maintain compatibility for existing users
• The podspec (React-RCTAppDelegate.podspec) automatically includes new .h and .mm files via podspec_sources, so no podspec changes were needed
• All UIScene APIs are properly guarded with availability checks

Screenshots

UIScene lifecycle adopted successfully - no warnings in Xcode console

---

Reviewers: @cipolleschi @huntie @cortinico

Please let me know if you'd like any changes to this implementation or if you prefer a different approach!

[react-native-bot]

	Fails
🚫	📋 Missing Changelog - Please add a Changelog to your PR description. See Changelog format

	Warnings
⚠️	📋 Missing Test Plan - Can you add a Test Plan? To do so, add a "## Test Plan" section to your PR description. A Test Plan lets us know how these changes were tested.

Generated by 🚫 dangerJS against c42884f

[cipolleschi]

We have an RFC in draft to fix this properly and holistically. Please bear with us while we refine it and we move that forward.
Also, ideally, we would want to get rid of the RCTAppDelegate completely.

[Srishtyshree]

@cipolleschi Thank you for the feedback. Based on your comment above (#issuecomment-3626363532), it sounds like this PR might be superseded by the upcoming RFC that aims to address the UIScene lifecycle more holistically and potentially remove RCTAppDelegate.

Should this PR be closed for now to await the RFC, or are there parts that could be adapted later?

[Srishtyshree]

Hi @cipolleschi, thank you for the information about the upcoming RFC.

While I understand the team is working on a more holistic solution, I believe this PR offers significant immediate value and can coexist with future plans:

1. Addresses an Imminent Issue: This PR resolves the "CLIENT OF UIKIT REQUIRES UPDATE" warning, which Apple has stated will become an assertion in future iOS versions. Merging this provides a proactive solution for developers who need to address this now.

2. Opt-In and Backward Compatible: The implementation is designed to be completely opt-in. It only activates when UIApplicationSceneManifest is present in Info.plist, ensuring zero breaking changes for existing apps not yet using scenes. Apps without the manifest continue to use the existing UIWindow flow.

3. Foundation for Future Work: The RCTSceneDelegate introduced here provides a functional implementation that could serve as a valuable base or be adapted when the RFC is finalized, rather than starting from scratch.

4. No Disruption to Existing Apps: The changes don't disrupt the current UIWindow based flow for apps that haven't opted into scenes. This allows for a gradual ecosystem transition.

5. Tested and Ready: The implementation has been manually tested with both scene-enabled and scene-disabled configurations, confirming it works correctly in both scenarios.

Could this PR be considered for merging as an interim solution that allows developers to adopt UIScene now, while the more comprehensive RFC is being refined? The opt-in nature ensures it won't force changes on those not ready and provides a clear migration path for those who are.

I'm also happy to adapt this work to align with the RFC once it's available, or close this PR if the team prefers to wait. Just wanted to make the case that this could provide immediate value without blocking future improvements.

[react-native-bot]

This PR is stale because it has been open for 180 days with no activity. It will be closed in 7 days unless you comment on it or remove the "Stale" label.