@callstack/react-native-brownfield 5.0.2 → 5.1.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @callstack/react-native-brownfield
 
+## 5.1.0
+
+### Minor Changes
+
+- [#450](https://github.com/callstack/react-native-brownfield/pull/450) [`4846a05`](https://github.com/callstack/react-native-brownfield/commit/4846a055eb06f8c8dea08b33d0bb0d1b2a2f2f86) Thanks [@borisyankov](https://github.com/borisyankov)! - Add `preloadBundle` to `startReactNative` on iOS. Without a preload, `startReactNative` only makes the factory, and React Native loads the JavaScript bundle when it creates the first React Native view. `startReactNative(launchOptions:preloadBundle:onBundleLoaded:)` moves that work to the app launch: the call starts the React Host, and React Native evaluates the bundle on the JavaScript thread, in parallel with the remainder of the app launch. On Android, `ReactNativeBrownfield.initialize` does the same operation. This shape of `startReactNative` also takes the launch options for the React Host.
+
+  `onBundleLoaded` now runs on the main thread, and not on the JavaScript thread. A callback that you add after React Native loaded the bundle runs in the next turn of the main run loop.
+
+### Patch Changes
+
+- [#381](https://github.com/callstack/react-native-brownfield/pull/381) [`b8e8da5`](https://github.com/callstack/react-native-brownfield/commit/b8e8da50fbf20058c5c2745981c7deb5cb33061a) Thanks [@alpharius-ck](https://github.com/alpharius-ck)! - e2e tests for android
+- Updated dependencies []:
+  - @callstack/brownfield-cli@5.1.0
+
 ## 5.0.2
 
 ### Patch Changes

package/android/src/main/java/com/callstack/reactnativebrownfield/ReactNativeBrownfield.kt

@@ -65,6 +65,8 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
             if (!initialized.getAndSet(true)) {
                 loadNativeLibs(application)
                 installAndPreload(reactHost, onJSBundleLoaded)
+            } else {
+                invokeWhenJSBundleLoaded(onJSBundleLoaded)
             }
         }
 
@@ -77,6 +79,8 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
             if (!initialized.getAndSet(true)) {
                 loadNativeLibs(application)
                 installAndPreload(reactHostFactory(), onJSBundleLoaded)
+            } else {
+                invokeWhenJSBundleLoaded(onJSBundleLoaded)
             }
         }
         
@@ -102,6 +106,8 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
                     jsRuntimeFactory = null
                 )
                 installAndPreload(reactHost, onJSBundleLoaded)
+            } else {
+                invokeWhenJSBundleLoaded(onJSBundleLoaded)
             }
         }
 
@@ -134,6 +140,25 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
                 onJSBundleLoaded?.invoke(true)
             }
         }
+
+        private fun invokeWhenJSBundleLoaded(onJSBundleLoaded: OnJSBundleLoaded?) {
+            if (onJSBundleLoaded == null || !::instance.isInitialized) {
+                return
+            }
+
+            val reactHost = instance.reactHost
+            reactHost.currentReactContext?.let {
+                onJSBundleLoaded.invoke(true)
+                return
+            }
+
+            reactHost.addReactInstanceEventListener(object : ReactInstanceEventListener {
+                override fun onReactContextInitialized(context: ReactContext) {
+                    onJSBundleLoaded.invoke(true)
+                    reactHost.removeReactInstanceEventListener(this)
+                }
+            })
+        }
     }
 
     /**

package/android/src/main/java/com/callstack/reactnativebrownfield/ReactNativeFragment.kt

@@ -69,6 +69,26 @@ class ReactNativeFragment : ReactFragment(), PermissionAwareActivity {
         }
     }
 
+    override fun onPause() {
+        try {
+            super.onPause()
+        } catch (error: AssertionError) {
+            if (
+                error.message?.contains(
+                    "Pausing an activity that is not the current activity"
+                ) == true
+            ) {
+                Log.w(
+                    "ReactNativeFragment",
+                    "Ignoring stale onHostPause for ${activity?.javaClass?.simpleName}",
+                    error
+                )
+                return
+            }
+            throw error
+        }
+    }
+
     override fun onRequestPermissionsResult(
         requestCode: Int,
         permissions: Array<String>,

package/ios/BrownfieldReactHostPreloader.h

@@ -0,0 +1,30 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Creates and starts the React Host, but does not create a view. React Native loads and evaluates
+ * the JavaScript bundle immediately, and not when it mounts the first React Native view.
+ * `viewWithModuleName:` makes the same call internally, thus a view that you create later uses the
+ * host that is ready.
+ *
+ * This class is in Objective-C, because Swift cannot make this call:
+ * `RCTReactNativeFactory.devMenuConfiguration` is nullable, but the related parameter is not
+ * nullable.
+ */
+@interface BrownfieldReactHostPreloader : NSObject
+
+/**
+ * Call this method on the main thread. If a host is already available, this method does nothing.
+ *
+ * @param reactNativeFactory An `RCTReactNativeFactory`, or a subclass, for example
+ *   `ExpoReactNativeFactory`. The type is `id`, because this header must stay free of the React
+ *   Native imports.
+ * @param launchOptions The launch options for the React Host.
+ */
++ (void)preloadWithReactNativeFactory:(id)reactNativeFactory
+                        launchOptions:(nullable NSDictionary *)launchOptions;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/BrownfieldReactHostPreloader.m

@@ -0,0 +1,113 @@
+#import "BrownfieldReactHostPreloader.h"
+
+// This file is plain Objective-C, and not Objective-C++. The umbrella header of
+// React-RCTAppDelegate imports the Hermes and JSI headers if `__cplusplus` is set. This pod does
+// not have the necessary search paths for those headers. Without C++, the compiler ignores those
+// imports. The compiler then builds the module in the same way that Swift imports it.
+//
+// The name of the pod changes if the build makes it a framework. Thus you must try each possible
+// name. Expo uses the same method in `RCTAppDelegateUmbrella.h`.
+#if __has_include(<React_RCTAppDelegate/RCTRootViewFactory.h>)
+#import <React_RCTAppDelegate/RCTReactNativeFactory.h>
+#import <React_RCTAppDelegate/RCTRootViewFactory.h>
+#elif __has_include(<React-RCTAppDelegate/RCTRootViewFactory.h>)
+#import <React-RCTAppDelegate/RCTReactNativeFactory.h>
+#import <React-RCTAppDelegate/RCTRootViewFactory.h>
+#else
+#import <React/RCTReactNativeFactory.h>
+#import <React/RCTRootViewFactory.h>
+#endif
+
+NS_ASSUME_NONNULL_BEGIN
+
+// `RCTBundleConfiguration` first exists in React Native 0.84. React Native 0.83 does not declare
+// the class. This forward declaration lets the file name the type with both versions.
+@class RCTBundleConfiguration;
+
+/**
+ * The two shapes of `initializeReactHostWithLaunchOptions:...`. React Native 0.83 has the shape
+ * without `bundleConfiguration:`. React Native 0.84 added that parameter and removed the earlier
+ * shape. No header tells the two versions apart at compile time, thus this file declares both
+ * shapes and `respondsToSelector:` selects one at run time. The declarations are equal to the
+ * React Native declarations. The compiler then accepts the file with both versions.
+ */
+@protocol BrownfieldReactHostInitializing <NSObject>
+
+- (void)initializeReactHostWithLaunchOptions:(NSDictionary *__nullable)launchOptions
+                         bundleConfiguration:(RCTBundleConfiguration *)bundleConfiguration
+                        devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration;
+
+- (void)initializeReactHostWithLaunchOptions:(NSDictionary *__nullable)launchOptions
+                        devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration;
+
+@end
+
+/**
+ * `RCTReactNativeFactory.bundleConfiguration` also first exists in React Native 0.84.
+ */
+@protocol BrownfieldBundleConfigurationProviding <NSObject>
+
+@property (nonatomic, readonly) RCTBundleConfiguration *bundleConfiguration;
+
+@end
+
+NS_ASSUME_NONNULL_END
+
+@implementation BrownfieldReactHostPreloader
+
++ (void)preloadWithReactNativeFactory:(id)reactNativeFactory
+                        launchOptions:(NSDictionary *_Nullable)launchOptions
+{
+  RCTReactNativeFactory *factory = (RCTReactNativeFactory *)reactNativeFactory;
+  RCTRootViewFactory *rootViewFactory = factory.rootViewFactory;
+
+  // `initializeReactHostWithLaunchOptions:...` returns early if a view, or an earlier preload,
+  // created a host. Thus this method makes no other check. React Native declares
+  // `rootViewFactory` as not nullable, and this guard is only a protection.
+  if (rootViewFactory == nil) {
+    return;
+  }
+
+  id<BrownfieldReactHostInitializing> hostInitializer = (id)rootViewFactory;
+  SEL initializeWithBundleConfiguration =
+      @selector(initializeReactHostWithLaunchOptions:bundleConfiguration:devMenuConfiguration:);
+  SEL initializeWithDevMenuConfiguration =
+      @selector(initializeReactHostWithLaunchOptions:devMenuConfiguration:);
+
+  // Get the configurations from the factory. Do not make new configurations from the default
+  // values. The Expo runtime sends `RCTReactNativeFactory.devMenuConfiguration` from
+  // `ExpoReactNativeFactory.recreateRootView:`, thus the factory value keeps the two runtimes
+  // equal.
+  //
+  // The preloaded host is equal to a host that a view creates later, but the two paths send
+  // different objects. The bare runtime creates the view with
+  // `viewWithModuleName:initialProperties:launchOptions:`, and that method sends
+  // `[RCTBundleConfiguration defaultConfiguration]` and `[RCTDevMenuConfiguration
+  // defaultConfiguration]`. The values are equal:
+  //   - `RCTReactNativeFactory.bundleConfiguration` gives `[RCTBundleConfiguration
+  //     defaultConfiguration]` while nobody sets another value.
+  //   - `RCTReactNativeFactory.devMenuConfiguration` is nil by default.
+  //     `RCTDevMenuConfigurationDecorator` does nothing with nil, and `RCTDevMenu` and
+  //     `RCTDevSettings` keep their own default values. Those values are equal to
+  //     `[RCTDevMenuConfiguration defaultConfiguration]`, because the two sides read `RCT_DEV_MENU`.
+  if ([hostInitializer respondsToSelector:initializeWithBundleConfiguration]) {
+    id<BrownfieldBundleConfigurationProviding> configurationProvider = (id)factory;
+
+    [hostInitializer initializeReactHostWithLaunchOptions:launchOptions
+                                      bundleConfiguration:configurationProvider.bundleConfiguration
+                                     devMenuConfiguration:factory.devMenuConfiguration];
+  } else if ([hostInitializer respondsToSelector:initializeWithDevMenuConfiguration]) {
+    [hostInitializer initializeReactHostWithLaunchOptions:launchOptions
+                                     devMenuConfiguration:factory.devMenuConfiguration];
+  } else {
+    // A React Native version with a third shape of the method. Do not crash. The first React
+    // Native view creates the host, as without a preload.
+    NSLog(
+        @"%@",
+        @"ReactNativeBrownfield: startReactNative did not preload the JavaScript bundle, because "
+        @"this React Native version has no known initializeReactHostWithLaunchOptions: method. The "
+        @"first React Native view loads the bundle.");
+  }
+}
+
+@end

package/ios/Expo/ExpoHostRuntime.swift

@@ -11,7 +11,7 @@ internal import EXUpdates
 final class ExpoHostRuntime {
   static let shared = ExpoHostRuntime()
 
-  private let jsBundleLoadObserver = JSBundleLoadObserver()
+  let preloadState = ReactHostPreloadState()
   private var delegate = ExpoHostRuntimeDelegate()
   private var reactNativeFactory: RCTReactNativeFactory?
   private var expoDelegate: ExpoAppDelegate?
@@ -35,9 +35,15 @@ final class ExpoHostRuntime {
   /**
    * Starts React Native with optional callback when bundle is loaded.
    *
-   * @param onBundleLoaded Optional callback invoked after JS bundle is fully loaded.
+   * @param onBundleLoaded Optional callback invoked on the main thread after JS bundle is fully loaded.
    */
   public func startReactNative(onBundleLoaded: (() -> Void)?) {
+    // The callback registration is outside of the guard below. An earlier `startReactNative` call
+    // can already have made the factory, and the callback must still run.
+    if let onBundleLoaded {
+      preloadState.jsBundleLoadObserver.observe(onBundleLoaded: onBundleLoaded)
+    }
+
     guard reactNativeFactory == nil else { return }
 
     let appDelegate = ExpoAppDelegate()
@@ -50,10 +56,6 @@ final class ExpoHostRuntime {
     appDelegate.bindReactNativeFactory(reactNativeFactory)
     #endif
     expoDelegate = appDelegate
-
-    if let onBundleLoaded {
-      jsBundleLoadObserver.observeOnce(onBundleLoaded: onBundleLoaded)
-    }
   }
 
   /**
@@ -70,6 +72,7 @@ final class ExpoHostRuntime {
     }
     reactNativeFactory = nil
     expoDelegate = nil
+    preloadState.reset()
   }
 
   /**
@@ -169,6 +172,8 @@ final class ExpoHostRuntime {
     let bundleURL = delegate.bundleURL()
     configureDevLoadingView(with: bundleURL)
 
+    let resolvedLaunchOptions = preloadState.launchOptions(overriddenBy: launchOptions)
+
     // below: https://github.com/expo/expo/commit/2013760c46cde1404872d181a691da72fbf207a4
     // has moved the recreateRootView method to ExpoReactNativeFactory
     #if EXPO_SDK_GTE_55  // this define comes from the Brownfield Expo config plugin
@@ -176,19 +181,51 @@ final class ExpoHostRuntime {
       withBundleURL: bundleURL,
       moduleName: moduleName,
       initialProps: initialProps,
-      launchOptions: launchOptions
+      launchOptions: resolvedLaunchOptions
     )
     #else
     return expoDelegate?.recreateRootView(
       withBundleURL: bundleURL,
       moduleName: moduleName,
       initialProps: initialProps,
-      launchOptions: launchOptions
+      launchOptions: resolvedLaunchOptions
     )
     #endif
   }
 }
 
+extension ExpoHostRuntime: ReactHostPreloading {
+  var reactNativeFactoryForPreload: AnyObject? {
+    return reactNativeFactory
+  }
+
+  /**
+   * expo-dev-launcher finds the Metro URL only after the user selects an app in the launcher. This
+   * is a Debug behavior. In Release the class is in the binary, but it does nothing. Thus this
+   * check is also only in Debug.
+   *
+   * The check reads the class name, because this pod has no dependency on expo-dev-launcher.
+   * `EXDevLauncherController` is the name in expo-dev-launcher 56 and 57. If a later version
+   * changes the name, this method gives `true`, and a preload can keep a bundle of the launcher
+   * screen. Examine the name again when you add a new Expo SDK.
+   *
+   * `ExpoHostRuntimeDelegate.isBundleURLStable` covers the other conditions.
+   */
+  func canPreloadReactNative() -> Bool {
+    #if DEBUG
+    if NSClassFromString("EXDevLauncherController") != nil {
+      return false
+    }
+    #endif
+
+    return delegate.isBundleURLStable
+  }
+
+  func prepareDevLoadingView() {
+    configureDevLoadingView()
+  }
+}
+
 class ExpoHostRuntimeDelegate: ExpoReactNativeFactoryDelegate {
   var entryFile = ".expo/.virtual-metro-entry"
   var bundlePath = "main.jsbundle"
@@ -242,5 +279,30 @@ class ExpoHostRuntimeDelegate: ExpoReactNativeFactoryDelegate {
       return nil
     }
   }
+
+  /**
+   * `true` if `bundleURL()` gives now the same result as a later resolution. This property follows
+   * the steps of `bundleURL()`, and it must change together with them.
+   *
+   * The override wins over every other step, thus an override makes the URL stable.
+   *
+   * expo-updates selects the launch asset while `AppController` starts. `ReactNativeViewController`
+   * starts `AppController`. Before this operation is complete, `launchAssetUrl()` is nil, and
+   * `bundleURL()` gives the embedded bundle. A host from that time keeps the embedded bundle, and
+   * Expo never applies the update. Thus the URL is stable only after `launchAssetUrl()` has a
+   * value. The class can be in the binary while the app does not use it, thus this check reads the
+   * state and not the class.
+   */
+  var isBundleURLStable: Bool {
+    if bundleURLOverride?() != nil {
+      return true
+    }
+
+    #if canImport(EXUpdates) && !DEBUG
+    return AppController.isInitialized() && AppController.sharedInstance.launchAssetUrl() != nil
+    #else
+    return true
+    #endif
+  }
 }
 #endif

package/ios/JSBundleLoadObserver.swift

@@ -1,38 +1,85 @@
 import Foundation
-internal import React
 
+/**
+ * Watches the `RCTInstanceDidLoadBundle` notification, and calls the callback that waits for it.
+ *
+ * React Native sends the notification from the JavaScript thread. This class always calls the
+ * callback on the main thread, because the callback changes the user interface.
+ *
+ * The class starts to watch at the initialization, and not at the first callback. The class then
+ * knows that React Native loaded the bundle, also if nobody waited for the notification.
+ */
 final class JSBundleLoadObserver {
-  private var onBundleLoaded: (() -> Void)?
+  private var pendingCallback: (() -> Void)?
+  private var didLoadBundle = false
   private var observerToken: NSObjectProtocol?
 
-  func observeOnce(onBundleLoaded: @escaping () -> Void) {
-    removeObserverIfNeeded()
-    self.onBundleLoaded = onBundleLoaded
-
+  init() {
     observerToken = NotificationCenter.default.addObserver(
       forName: NSNotification.Name("RCTInstanceDidLoadBundle"),
       object: nil,
-      queue: nil
+      queue: .main
     ) { [weak self] _ in
-      self?.notifyAndClear()
+      self?.bundleDidLoad()
     }
   }
 
   deinit {
-    removeObserverIfNeeded()
+    if let observerToken {
+      NotificationCenter.default.removeObserver(observerToken)
+    }
+  }
+
+  /**
+   * Keeps one callback, and calls it one time. A new callback replaces the callback that waits. If
+   * React Native already loaded the bundle, the class calls the callback in the next turn of the
+   * main run loop.
+   *
+   * @param onBundleLoaded The class always calls this callback on the main thread.
+   */
+  func observe(onBundleLoaded: @escaping () -> Void) {
+    onMainThread { [weak self] in
+      self?.register(onBundleLoaded)
+    }
+  }
+
+  /**
+   * Removes the callback that waits, and forgets the bundle of the earlier session. Call this
+   * method when you stop React Native. A callback of the earlier session must not run in the next
+   * session.
+   */
+  func reset() {
+    onMainThread { [weak self] in
+      self?.pendingCallback = nil
+      self?.didLoadBundle = false
+    }
   }
 
-  private func notifyAndClear() {
-    let callback = onBundleLoaded
-    onBundleLoaded = nil
-    removeObserverIfNeeded()
+  // MARK: - Main thread only
+
+  private func register(_ onBundleLoaded: @escaping () -> Void) {
+    guard !didLoadBundle else {
+      DispatchQueue.main.async(execute: onBundleLoaded)
+      return
+    }
+
+    pendingCallback = onBundleLoaded
+  }
+
+  private func bundleDidLoad() {
+    didLoadBundle = true
+
+    let callback = pendingCallback
+    pendingCallback = nil
+
     callback?()
   }
 
-  private func removeObserverIfNeeded() {
-    if let observerToken {
-      NotificationCenter.default.removeObserver(observerToken)
-      self.observerToken = nil
+  private func onMainThread(_ work: @escaping () -> Void) {
+    if Thread.isMainThread {
+      work()
+    } else {
+      DispatchQueue.main.async(execute: work)
     }
   }
 }

package/ios/ReactHostPreloading.swift

@@ -0,0 +1,177 @@
+import Foundation
+
+/**
+ * The preload state that `startReactNative`, `view` and `stopReactNative` share.
+ */
+final class ReactHostPreloadState {
+  let jsBundleLoadObserver = JSBundleLoadObserver()
+
+  private let lock = NSLock()
+  private var storedLaunchOptions: [AnyHashable: Any]?
+  private var hasPreloadRequest = false
+
+  /**
+   * Keeps the launch options of a `startReactNative` call.
+   *
+   * `startReactNative` can move its preload work to the main thread. A view on the main thread can
+   * create the React Host before that. Thus this method must run at the call, and not after the
+   * change of thread. The view then finds the options.
+   */
+  func storeLaunchOptions(_ launchOptions: [AnyHashable: Any]?) {
+    guard let launchOptions else { return }
+
+    lock.lock()
+    defer { lock.unlock() }
+
+    storedLaunchOptions = launchOptions
+  }
+
+  /**
+   * Records that a `startReactNative` call must preload the bundle. `consumePreloadRequest` reads
+   * the request one time, and `reset` cancels it.
+   */
+  func requestPreload() {
+    lock.lock()
+    defer { lock.unlock() }
+
+    hasPreloadRequest = true
+  }
+
+  /**
+   * `true` if a preload request waits. The method also removes the request.
+   *
+   * `startReactNative` can move its preload work to the main thread. `stopReactNative` on the main
+   * thread can run before that work. The stop cancels the request, thus this method then gives
+   * `false`, and React Native stays stopped.
+   */
+  func consumePreloadRequest() -> Bool {
+    lock.lock()
+    defer { lock.unlock() }
+
+    let hadRequest = hasPreloadRequest
+    hasPreloadRequest = false
+
+    return hadRequest
+  }
+
+  /**
+   * The launch options for a call that can create the React Host. The options of the caller win
+   * over the options of an earlier `startReactNative` call.
+   */
+  func launchOptions(
+    overriddenBy explicitLaunchOptions: [AnyHashable: Any]? = nil
+  ) -> [AnyHashable: Any]? {
+    lock.lock()
+    defer { lock.unlock() }
+
+    return explicitLaunchOptions ?? storedLaunchOptions
+  }
+
+  /**
+   * Removes the state of the session. Call this method when you stop React Native.
+   */
+  func reset() {
+    jsBundleLoadObserver.reset()
+
+    lock.lock()
+    defer { lock.unlock() }
+
+    storedLaunchOptions = nil
+    hasPreloadRequest = false
+  }
+}
+
+/**
+ * The preload sequence that the two host runtimes share. Only one runtime is in a build. The
+ * shared sequence keeps the behavior of the two runtimes equal.
+ */
+protocol ReactHostPreloading: AnyObject {
+  var preloadState: ReactHostPreloadState { get }
+
+  /**
+   * The React Native factory, or nil while React Native did not start. The type is `AnyObject`,
+   * because `BrownfieldReactHostPreloader` also takes the factory as `id`. This file then needs no
+   * React Native import, and it builds with both runtimes.
+   */
+  var reactNativeFactoryForPreload: AnyObject? { get }
+
+  func startReactNative()
+
+  /**
+   * `false` while the bundle URL can still change. The runtime must not create the host in this
+   * condition, because the host keeps the first bundle that it evaluates.
+   */
+  func canPreloadReactNative() -> Bool
+
+  func prepareDevLoadingView()
+}
+
+extension ReactHostPreloading {
+  /**
+   * The implementation of
+   * `ReactNativeBrownfield.startReactNative(launchOptions:preloadBundle:onBundleLoaded:)`, which
+   * holds the contract.
+   */
+  func startReactNative(
+    launchOptions: [AnyHashable: Any]?,
+    preloadBundle: Bool,
+    onBundleLoaded: (() -> Void)?
+  ) {
+    preloadState.storeLaunchOptions(launchOptions)
+
+    if let onBundleLoaded {
+      preloadState.jsBundleLoadObserver.observe(onBundleLoaded: onBundleLoaded)
+    }
+
+    guard preloadBundle else {
+      startReactNative()
+      return
+    }
+
+    preloadState.requestPreload()
+
+    if Thread.isMainThread {
+      createReactHost()
+    } else {
+      DispatchQueue.main.async { [weak self] in
+        self?.createReactHost()
+      }
+    }
+  }
+
+  private func createReactHost() {
+    // `stopReactNative` can run between the request and this method, because a caller that is not
+    // on the main thread moves the work to the main thread. The stop cancels the request, and
+    // React Native must then stay stopped.
+    guard preloadState.consumePreloadRequest() else { return }
+
+    startReactNative()
+
+    guard let factory = reactNativeFactoryForPreload else {
+      logSkippedPreload("React Native did not make the factory")
+      return
+    }
+
+    guard canPreloadReactNative() else {
+      logSkippedPreload("the bundle URL can still change")
+      return
+    }
+
+    // You must configure the dev loading view before React Native loads the bundle. Usually the
+    // `view` method does this.
+    prepareDevLoadingView()
+
+    BrownfieldReactHostPreloader.preload(
+      withReactNativeFactory: factory,
+      launchOptions: preloadState.launchOptions()
+    )
+  }
+
+  private func logSkippedPreload(_ reason: String) {
+    NSLog(
+      "%@",
+      "ReactNativeBrownfield: startReactNative did not preload the JavaScript bundle, because "
+        + reason + ". The first React Native view loads the bundle."
+    )
+  }
+}

package/ios/ReactNativeBrownfield.swift

@@ -192,7 +192,9 @@ internal import Expo
   /**
    * Starts React Native with optional callback when bundle is loaded.
    *
-   * @param onBundleLoaded Optional callback invoked after JS bundle is fully loaded.
+   * @param onBundleLoaded Optional callback invoked on the main thread after the JS bundle is
+   *   fully loaded. It runs in the next turn of the main run loop when the bundle is already
+   *   loaded. A new callback replaces the callback that waits.
    */
   @objc public func startReactNative(onBundleLoaded: (() -> Void)?) {
     #if canImport(Expo)
@@ -202,6 +204,39 @@ internal import Expo
     #endif
   }
 
+  /**
+   * Starts React Native, and optionally loads the JavaScript bundle immediately. Without a
+   * preload, React Native loads the bundle when it creates the first React Native view. On
+   * Android, `ReactNativeBrownfield.initialize` does the same operation.
+   *
+   * @param launchOptions The launch options for the React Host. Only the call that creates the
+   *   host reads these options. This method keeps the options. A view that creates the host later
+   *   uses them, also if this method cannot create the host. Options that you give to `view` win
+   *   over these options.
+   * @param preloadBundle `true` loads and evaluates the JavaScript bundle now. A preload adds
+   *   work to the section of the caller, but the first React Native screen appears faster.
+   * @param onBundleLoaded An optional callback, with the rules of `startReactNative`.
+   */
+  @objc public func startReactNative(
+    launchOptions: [AnyHashable: Any]?,
+    preloadBundle: Bool,
+    onBundleLoaded: (() -> Void)?
+  ) {
+    #if canImport(Expo)
+    ExpoHostRuntime.shared.startReactNative(
+      launchOptions: launchOptions,
+      preloadBundle: preloadBundle,
+      onBundleLoaded: onBundleLoaded
+    )
+    #else
+    ReactNativeHostRuntime.shared.startReactNative(
+      launchOptions: launchOptions,
+      preloadBundle: preloadBundle,
+      onBundleLoaded: onBundleLoaded
+    )
+    #endif
+  }
+
   /**
    * Send a serialized JSON message to the React Native JS application.
    * The message is delivered as a `brownfieldMessage` DeviceEventEmitter event.

package/ios/Vanilla/ReactNativeHostRuntime.swift

@@ -46,7 +46,7 @@ class ReactNativeBrownfieldDelegate: RCTDefaultReactNativeFactoryDelegate {
 
 final class ReactNativeHostRuntime {
   public static let shared = ReactNativeHostRuntime()
-  private let jsBundleLoadObserver = JSBundleLoadObserver()
+  let preloadState = ReactHostPreloadState()
   private var delegate = ReactNativeBrownfieldDelegate()
 
   private func configureDevLoadingView() {
@@ -133,6 +133,7 @@ final class ReactNativeHostRuntime {
     }
 
     reactNativeFactory = nil
+    preloadState.reset()
   }
 
   public func view(
@@ -145,7 +146,7 @@ final class ReactNativeHostRuntime {
     return reactNativeFactory?.rootViewFactory.view(
       withModuleName: moduleName,
       initialProperties: initialProps,
-      launchOptions: launchOptions
+      launchOptions: preloadState.launchOptions(overriddenBy: launchOptions)
     )
   }
 
@@ -188,17 +189,38 @@ final class ReactNativeHostRuntime {
   /**
    * Starts React Native with optional callback when bundle is loaded.
    *
-   * @param onBundleLoaded Optional callback invoked after JS bundle is fully loaded.
+   * @param onBundleLoaded Optional callback invoked on the main thread after JS bundle is fully loaded.
    */
   public func startReactNative(onBundleLoaded: (() -> Void)?) {
+    // The callback registration is outside of the guard below. An earlier `startReactNative` call
+    // can already have made the factory, and the callback must still run.
+    if let onBundleLoaded {
+      preloadState.jsBundleLoadObserver.observe(onBundleLoaded: onBundleLoaded)
+    }
+
     guard reactNativeFactory == nil else { return }
 
     delegate.dependencyProvider = RCTAppDependencyProvider()
     reactNativeFactory = RCTReactNativeFactory(delegate: delegate)
+  }
+}
 
-    if let onBundleLoaded {
-      jsBundleLoadObserver.observeOnce(onBundleLoaded: onBundleLoaded)
-    }
+extension ReactNativeHostRuntime: ReactHostPreloading {
+  var reactNativeFactoryForPreload: AnyObject? {
+    return reactNativeFactory
+  }
+
+  /**
+   * The bare React Native delegate resolves the bundle URL from the override, from Metro, or from
+   * the embedded bundle. No step waits for an asynchronous operation. Thus a preload uses the same
+   * bundle as the first view.
+   */
+  func canPreloadReactNative() -> Bool {
+    return true
+  }
+
+  func prepareDevLoadingView() {
+    configureDevLoadingView()
   }
 }
 #endif

package/lib/commonjs/expo-config-plugin/template/android/ReactNativeHostManager.post55.kt

@@ -7,10 +7,15 @@ import com.callstack.reactnativebrownfield.ReactNativeBrownfield
 import com.facebook.react.PackageList
 import expo.modules.ApplicationLifecycleDispatcher
 import expo.modules.ExpoReactHostFactory
+import java.util.concurrent.atomic.AtomicBoolean
 
 object ReactNativeHostManager {
+    private val applicationCreateDispatched = AtomicBoolean()
+
     fun initialize(application: Application, onJSBundleLoaded: OnJSBundleLoaded? = null) {
-        ApplicationLifecycleDispatcher.onApplicationCreate(application)
+        if (applicationCreateDispatched.compareAndSet(false, true)) {
+            ApplicationLifecycleDispatcher.onApplicationCreate(application)
+        }
 
         ReactNativeBrownfield.initialize(application, onJSBundleLoaded) {
             ExpoReactHostFactory.getDefaultReactHost(

package/lib/module/expo-config-plugin/template/android/ReactNativeHostManager.post55.kt

@@ -7,10 +7,15 @@ import com.callstack.reactnativebrownfield.ReactNativeBrownfield
 import com.facebook.react.PackageList
 import expo.modules.ApplicationLifecycleDispatcher
 import expo.modules.ExpoReactHostFactory
+import java.util.concurrent.atomic.AtomicBoolean
 
 object ReactNativeHostManager {
+    private val applicationCreateDispatched = AtomicBoolean()
+
     fun initialize(application: Application, onJSBundleLoaded: OnJSBundleLoaded? = null) {
-        ApplicationLifecycleDispatcher.onApplicationCreate(application)
+        if (applicationCreateDispatched.compareAndSet(false, true)) {
+            ApplicationLifecycleDispatcher.onApplicationCreate(application)
+        }
 
         ReactNativeBrownfield.initialize(application, onJSBundleLoaded) {
             ExpoReactHostFactory.getDefaultReactHost(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callstack/react-native-brownfield",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "license": "MIT",
   "author": "Michal Chudziak <mike.chudziak@callstack.com>",
   "bin": {
@@ -89,7 +89,7 @@
     "@expo/config-plugins": ">=54 <100"
   },
   "dependencies": {
-    "@callstack/brownfield-cli": "^5.0.2"
+    "@callstack/brownfield-cli": "^5.1.0"
   },
   "devDependencies": {
     "@babel/core": "^7.29.6",

package/src/expo-config-plugin/template/android/ReactNativeHostManager.post55.kt

@@ -7,10 +7,15 @@ import com.callstack.reactnativebrownfield.ReactNativeBrownfield
 import com.facebook.react.PackageList
 import expo.modules.ApplicationLifecycleDispatcher
 import expo.modules.ExpoReactHostFactory
+import java.util.concurrent.atomic.AtomicBoolean
 
 object ReactNativeHostManager {
+    private val applicationCreateDispatched = AtomicBoolean()
+
     fun initialize(application: Application, onJSBundleLoaded: OnJSBundleLoaded? = null) {
-        ApplicationLifecycleDispatcher.onApplicationCreate(application)
+        if (applicationCreateDispatched.compareAndSet(false, true)) {
+            ApplicationLifecycleDispatcher.onApplicationCreate(application)
+        }
 
         ReactNativeBrownfield.initialize(application, onJSBundleLoaded) {
             ExpoReactHostFactory.getDefaultReactHost(