Skip to content

feat(ios): UIScene life cycle support and React Native 0.88 support - #8374

Draft
yedidyak wants to merge 1 commit into
masterfrom
yedidyak/uiscene-rn88-460234
Draft

yedidyak wants to merge 1 commit into
masterfrom
yedidyak/uiscene-rn88-460234

Conversation

@yedidyak

@yedidyak yedidyak commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Why

Apps built with the iOS 27 SDK (Xcode 27) must adopt the UIScene life cycle. Without it, UIKit refuses to launch them: Application failed to launch: UIScene life cycle is required for apps built with this SDK.

RNN assumed the app-delegate window model throughout:

This PR adds opt-in UIScene support. It also makes RNN build and run on React Native 0.88, the first RN with built-in SceneDelegate support. RN 0.79+ keeps working, and apps without a scene manifest are unchanged.

What changed (iOS)

Windows

  • +[ReactNativeNavigation mainWindow] is the single main-window accessor and replaces every delegate.window read. delegate.window still points at the same window, so libraries that read it (Sentry, etc.) keep working.
  • New +[ReactNativeNavigation attachMainWindowToScene:]. It moves the existing main window to the scene, or creates it with initWithWindowScene:, then calls makeKeyAndVisible.
  • Overlay windows (fixes showOverlay creates a scene-less UIWindow, so overlays never appear under UIScene lifecycle #8345) and bottom-tab preload windows are created in the main window's scene when the app uses the scene life cycle (RNNSceneUtils). App-delegate apps still get initWithFrame:.
  • UIApplication.keyWindow and statusBarFrame reads go through scene-aware helpers. They are unchanged for app-delegate apps.
  • RNNSplashScreenViewController showOnWindow: uses the window it is given.

RNNSceneDelegate (new public base class, the counterpart of RNNAppDelegate)

  • scene:willConnectToSession:options: attaches the main window. It exposes launchURLContexts, launchUserActivities and launchURL, and dispatches the cold-start links through dispatchLaunchLinksFromConnectionOptions:scene:. That gives cold-start parity with the app-delegate path; subclasses can override it.
  • scene:openURLContexts: and scene:continueUserActivity: (browsing web) forward to RNN's deep-link queue.
  • RNNAppDelegate still creates the React host in didFinishLaunching.

Deep-link queue (R5a)

  • The pre-runtime queue moved from RNNAppDelegate to RNNDeepLinkDispatcher, behind +[ReactNativeNavigation dispatchDeepLinkURL:], +dispatchOpenURLContexts:inScene: and +dispatchUserActivity:inScene:. -[RNNAppDelegate dispatchDeepLinkURL:] stays public and forwards to it.
  • The queue stores what iOS delivered (NSURL, UIOpenURLContexts, NSUserActivity). It replays each entry through the matching API:
    • RN ≥ 0.88 and RCTIsSceneDelegateApp(): +[RCTLinkingManager scene:openURLContexts:] (one context per call, because RN only forwards the first) or +scene:continueUserActivity:;
    • otherwise: the existing +application:openURL:options:.
  • The gate is a new compile-time macro, RNN_RN_VERSION_88_OR_NEWER (in RNNReactNativeVersion.h, from REACT_NATIVE_VERSION_MINOR in <cxxreact/ReactNativeVersion.h>, which RN has had since at least 0.79). It sits alongside the existing RNN_RN_VERSION_* macros.
  • Only public UIKit and RN API is used: no swizzling, and RNN never posts RCTOpenURLNotification itself.

RN 0.88 compile fixes

  • RCTAppSetupPrepareApp and RCTEnableTurboModuleInteropBridgeProxy were removed in 0.88. They are gated off on 0.88; RNN keeps the debug idle-timer behavior and still calls RCTEnableTurboModuleInterop.
  • Unused imports of the removed RCTSafeAreaView.h and RCTRootContentView.h are guarded with __has_include.

Decision for maintainers: app-generated URLs on RN ≥ 0.88 under scenes

URLs an app builds itself and passes to dispatchDeepLinkURL: (notification handlers, push SDKs) have no UIOpenURLContext. On RN ≥ 0.88 in a scene app, RN's app-delegate Linking methods return NO and deliver nothing, and apps can't construct a UIOpenURLContext.

Implemented (option b):

  • Document the limitation.
  • RNN logs a warning when such a link isn't delivered, instead of dropping it silently.
  • Document the public workaround for the app's own custom scheme: [UIApplication.sharedApplication openURL:url options:@{} completionHandler:nil] makes iOS deliver the link to scene:openURLContexts:. The playground uses it for notification taps.
  • OS-delivered links (custom schemes, universal links) work on every RN version.

Question (option a): should RNN own a JS deep-link event, for example Navigation.events().registerDeepLinkListener, so app-generated URLs reach LinkingHandler without going through Linking? It would cover non-custom-scheme URLs as well. I didn't build it here; I'd like a maintainer decision first.

RN version support

RN What How it's validated
0.77 / 0.78 unchanged code paths existing ios_rn_78 lane
0.79.7 the Wix engine's version manual run (see below), versionMapping entries added
0.84 / 0.85.2 unchanged; scene path replays via the app-delegate API existing lanes + new ios_rn_85_scene
0.88.0 new new ios_rn_88 and ios_rn_88_scene lanes

The playground default stays 0.85.2, and Android is untouched; this PR is iOS-only. Version-switch changes in scripts/versionMapping.js:

  • for 0.88: CLI 20.2.0, gradle 9.4.1, reanimated 4.7.1, worklets 0.13.0, and gesture-handler 2.33.1, because 2.30 imports a header RN 0.88 removed;
  • for 0.79: CLI 18.0.0, reanimated 3.18.0, worklets removed.

changeReactNativeVersion.js honors YARN_NPM_REGISTRY_SERVER / npm_config_registry.

Manual RN 0.79 run:

REACT_NATIVE_VERSION=0.79.7 node scripts/changeReactNativeVersion.js && yarn install && yarn pod-install
cd playground && detox build -c ios.sim.release.scene && detox test -c ios.sim.release.scene

Playground and tests

  • New app target playgroundScene: same sources, plus SceneDelegate (an RNNSceneDelegate subclass) and Info-Scene.plist with a scene manifest. It has the same bundle id, so only one of the two apps is installed at a time and the URL scheme is unambiguous. Schemes: playgroundScene / playgroundScene_release.
  • New test target NavigationSceneTests: the full NavigationTests suite hosted by playgroundScene.
  • New unit tests: RNNSceneUtilsTest (window helper with and without a scene, attach) and RNNDeepLinkDispatcherTest (queueing, order, replay API selection).
  • Detox:
    • new ios.sim.{debug,release}.scene configurations;
    • new --scene flag for test-e2e / test-unit, and IOS_LIFECYCLE=scene in ci.ios.sh;
    • DETOX_IOS_DEVICE / DETOX_IOS_OS / DETOX_IOS_DERIVED_DATA overrides.
  • Deep-link e2e under scenes: Detox's device.openURL calls application:openURL:options:, which UIKit never calls in scene apps. Scene runs therefore open URLs through the notification handler, which re-opens the app's own scheme so iOS delivers a real UIOpenURLContext. xcrun simctl openurl takes the same path but shows an "Open in…?" prompt that Detox can't accept; I verified it by hand.
  • Deployment target: raised from 11–13 to 15.1 (RN's minimum). A Podfile post_install raises pods below it, because Xcode 27 rejects deployment targets below iOS 15.

Validation

All of these ran locally; CI has not run yet. Simulator runtimes: iOS 26.3.1 and iOS 27.2. Detox ran with one worker and --retries 1.

Check RN Xcode iOS Result
Build playground_release + playgroundScene_release 0.88.0 26.2 — ✅
Build playground_release + playgroundScene_release 0.88.0 27.2 (27B52) — ✅
Build both schemes 0.79.7 26.2 — ✅ (Xcode 27 can't build RN < 0.86: fmt vs clang 21)
Launch scene app 0.88.0 27.2 27.2 ✅ renders
Launch app-delegate app (control) 0.88.0 27.2 27.2 ✅ refused as expected: "UIScene life cycle is required for apps built with this SDK"
Detox, full suite, app-delegate 0.88.0 26.2 26.3 ✅ 20/20 suites (SideMenu passed on retry)
Detox, full suite, scene 0.88.0 26.2 26.3 ✅ 20/20 suites, 173 passed, 0 retries
Detox, key suites, scene (DeepLinking, Overlay, BottomTabs, Modals, SetRoot, Orientation, ApplicationLifecycle) 0.88.0 27.2 27.2 5/7 suites ✅. 3 tests fail on top-bar button hittability; the same tests fail with the app-delegate build on iOS 27.2, so it's iOS 27, not scenes (see follow-ups)
Detox, key suites, app-delegate 0.79.7 26.2 26.3 ✅ 7/7
Detox, key suites, scene 0.79.7 26.2 26.3 ✅ 7/7. 2 launch timeouts on the first run passed on rerun
Unit tests NavigationTests (app-delegate host) 0.88.0 26.2 26.3 392 tests; only testTopBarNoBorderOff fails (nav-bar appearance, untouched here; not checked against master on this runtime)
Unit tests NavigationSceneTests (scene host) 0.88.0 26.2 26.3 392 tests; same single failure
New unit tests (RNNSceneUtilsTest, RNNDeepLinkDispatcherTest) 0.88.0 26.2 26.3 ✅ 15/15 in both hosts
Manual: warm simctl openurl under scenes → "Open" → modal 0.88.0 26.2 26.3 ✅
yarn test-js 0.88.0 — — ✅

Deep links: cold-start and warm custom-scheme links and notification taps are covered by e2e under both life cycles. Universal links (NSUserActivity) are covered by unit tests only, because the playground has no associated domain.

Not run locally: a build on the default RN 0.85.2 (the new ios_rn_85* lanes cover it), the CI-pinned iOS 15.5 unit-test simulator, and Android (untouched).

Not covered / follow-ups

  • iOS 27 top bar (independent of scenes): on iOS 27.2, top-bar and back-button e2e tests fail on visibility/hittability with both life cycles (ExternalComponent, Buttons, BackButton, plus some Modals and DeepLinking close-button tests).
  • iPhone Duo / regular-width scenes: under scenes, the iOS 27.2 "iPhone Duo" simulator gives the app its 951×669 inner display, and UIKit lays the RNN tab bar out vertically on the right edge, under the status strip. App-delegate builds run letterboxed and don't show this.
  • Option (a) above: an RNN-owned deep-link event for app-generated URLs.
  • startReactNativeWithModuleName:inWindow:connectionOptions: (RN 0.88): RNN still creates the React host in the app delegate, so under scenes Linking.getInitialURL() returns null. RNN's LinkingHandler still gets the link via the url event. Revisit once RNN's minimum RN is 0.88.
  • npx rnn-link doesn't handle the RN 0.88 template's SceneDelegate yet. The docs describe the manual change.
  • Single scene only; multi-window iPad is out of scope.

Apps built with the iOS 27 SDK must adopt the UIScene life cycle. Everything here is opt-in:
apps without a UIApplicationSceneManifest behave as before.

- +[ReactNativeNavigation mainWindow] is the single main-window accessor (replaces every
  delegate.window read; delegate.window keeps pointing at the same window).
- +[ReactNativeNavigation attachMainWindowToScene:] attaches the main window to a UIWindowScene.
- Overlay windows (#8345) and bottom-tab preload windows are created in the main window's scene;
  keyWindow / statusBarFrame reads go through scene-aware helpers (RNNSceneUtils).
- New RNNSceneDelegate base class: attaches the window, forwards scene:openURLContexts: and
  scene:continueUserActivity:, dispatches cold-start links from the connection options.
- Deep-link queue moved to RNNDeepLinkDispatcher behind +[ReactNativeNavigation
  dispatchDeepLinkURL:] (-[RNNAppDelegate dispatchDeepLinkURL:] stays public). It keeps the
  UIOpenURLContexts / NSUserActivities iOS delivered and replays them through
  +[RCTLinkingManager scene:...] on RN >= 0.88 in scene apps (RNN_RN_VERSION_88_OR_NEWER +
  RCTIsSceneDelegateApp()), otherwise through the app-delegate API. App-generated URLs that
  RN >= 0.88 drops under scenes are logged.
- RN 0.88: gate the removed RCTAppSetupPrepareApp / interop bridge proxy, guard removed legacy
  header imports.
- Playground: playgroundScene app target and NavigationSceneTests (scene-hosted unit tests),
  scene schemes and Detox configs, deployment target 15.1 (Xcode 27), new unit tests for the
  window helper and the deep-link queue.
- CI / version switch: ios_rn_88, ios_rn_85_scene, ios_rn_88_scene lanes; versionMapping
  entries for 0.79 and 0.88; registry override for changeReactNativeVersion.js.
- Docs: ios/ARCHITECTURE.md, "Adopting UIScene (iOS)", deep linking under the UIScene life cycle.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

showOverlay creates a scene-less UIWindow, so overlays never appear under UIScene lifecycle

1 participant