iOS: Add new RCTCustomBundleConfiguration for modifying bundle URL (#54006)

Summary:
Following the [RFC](react-native-community/discussions-and-proposals#933), this PR introduces a new `RCTCustomBundleConfiguration` interface for modifying the bundle URL and exposes a new API for setting its instance in the `RCTReactNativeFactory`. The configuration object includes:

- bundleFilePath - the URL of the bundle to load from the file system,
- packagerServerScheme - the server scheme (e.g. http or https) to use when loading from the packager,
- packagerServerHost - the server host (e.g. localhost) to use when loading from the packager.

It associates `RCTPackagerConnection` (previously singleton) with the `RCTDevSettings` instance, which has access to the `RCTBundleManager`, which contains the specified configuration object. The connection is now established in the `RCTDevSettings initialize`  method, called after the bundle manager is set by invoking the new `startWithBundleManager` method on the `RCTPackagerConnection`.

The `RCTCustomBundleConfiguration` allows only for either `bundleFilePath` or `(packagerServerScheme, packagerServerHost)` to be set by defining appropriate initializers. 

The logic for creating bundle URL query items is extracted to a separate `createJSBundleURLQuery` method and is used by `RCTBundleManager` to set the configured `packagerServerHost` and `packagerServerScheme`. If the configuration is not defined, the `getBundleURL` method returns the result of the passed `fallbackURLProvider`.

The `bundleFilePath` should be created with `[NSURL fileURLWithPath:<path>]`, as otherwise the HMR client is created and fails ungracefully. The check is added in the `getBundle` method to log the error beforehand:

<img width="306" height="822" alt="Simulator Screenshot - iPhone 16 Pro - 2025-10-15 at 17 09 58" src="https://github.com/user-attachments/assets/869eed16-c5d8-4204-81d7-bd9cd42b2223" />

When the `bundleFilePath` is set in the `RCTCustomBundleConfiguration` the `Connect to Metro...` message shouldn't be suggested.

## Changelog:

[IOS][ADDED] - Add new `RCTCustomBundleConfiguration` for modifying bundle URL on `RCTReactNativeFactory`.


Test Plan:
Tested changing `packagerServerHost` from the `AppDelegate` by re-creating the React Native instance with updated `RCTCustomBundleConfiguration`. I've run two Metro instances, each serving a different JS bundle (changed background) on `8081` and `8082` ports. The native `Restart RN:<current port>` button on top of the screen toggles between ports (used in bundle configuration) and re-creates connections. Tested with `RCT_DEV` set to true and false.

https://github.com/user-attachments/assets/fd57068b-869c-4f45-93be-09d33f691cea


For setting bundle source from a file, I've generated bundle with a blue background and created a custom bundle configuration using `initWithBundleFilePath`. I've run the app without starting Metro:

<img width="306" height="822" alt="Simulator Screenshot - iPhone 16 Pro - 2025-10-15 at 17 06 21" src="https://github.com/user-attachments/assets/8283f202-0150-4e93-a4a9-d2b6ea6f1c37" />


<details>

<summary>code:</summary>

`AppDelegate.mm`

```objc
#import "AppDelegate.h"

#import <UserNotifications/UserNotifications.h>

#import <React/RCTBundleManager.h>
#import <React/RCTBundleURLProvider.h>
#import <React/RCTDefines.h>
#import <React/RCTLinkingManager.h>
#import <ReactCommon/RCTSampleTurboModule.h>
#import <ReactCommon/RCTTurboModuleManager.h>

#import <React/RCTPushNotificationManager.h>

#import <NativeCxxModuleExample/NativeCxxModuleExample.h>
#ifndef RN_DISABLE_OSS_PLUGIN_HEADER
#import <RNTMyNativeViewComponentView.h>
#endif

#if __has_include(<ReactAppDependencyProvider/RCTAppDependencyProvider.h>)
#define USE_OSS_CODEGEN 1
#import <ReactAppDependencyProvider/RCTAppDependencyProvider.h>
#else
#define USE_OSS_CODEGEN 0
#endif

static NSString *kBundlePath = @"js/RNTesterApp.ios";

interface AppDelegate () <UNUserNotificationCenterDelegate>
end

implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  self.launchOptions = launchOptions;
  self.port = @"8081";
  
#if USE_OSS_CODEGEN
  self.dependencyProvider = [RCTAppDependencyProvider new];
#endif

  self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
  
  [self startReactNative];

  [[UNUserNotificationCenter currentNotificationCenter] setDelegate:self];

  return YES;
}

- (void)startReactNative
{
  self.reactNativeFactory = [[RCTReactNativeFactory alloc] initWithDelegate:self];
  
  NSString *packagerServerHost = [NSString stringWithFormat:@"localhost:%@", self.port];
  
  RCTCustomBundleConfiguration *customBundleConfiguration =
      [[RCTCustomBundleConfiguration alloc] initWithPackagerServerScheme:@"http" packagerServerHost:packagerServerHost bundlePath:kBundlePath];

  self.reactNativeFactory.customBundleConfiguration = customBundleConfiguration;
  
  [self.reactNativeFactory startReactNativeWithModuleName:@"RNTesterApp"
                                                 inWindow:self.window
                                        initialProperties:[self prepareInitialProps]
                                            launchOptions:self.launchOptions];
  
  [self createTopButton];
}

- (void)createTopButton
{
  NSString *title = [NSString stringWithFormat:@"Restart RN:%@", self.port];
  
  self.topButton = [UIButton buttonWithType:UIButtonTypeSystem];
  [self.topButton setTitle:title forState:UIControlStateNormal];
  [self.topButton setBackgroundColor:[UIColor colorWithRed:0.0 green:0.5 blue:1.0 alpha:1]];
  [self.topButton setTitleColor:[UIColor whiteColor] forState:UIControlStateNormal];

  CGFloat buttonWidth = 120;
  CGFloat buttonHeight = 44;
  CGFloat screenWidth = [UIScreen mainScreen].bounds.size.width;

  self.topButton.frame = CGRectMake((screenWidth - buttonWidth) / 2, 50, buttonWidth, buttonHeight);
  self.topButton.layer.cornerRadius = 8;
  [self.topButton addTarget:self action:selector(buttonTapped:) forControlEvents:UIControlEventTouchUpInside];
  [self.window addSubview:self.topButton];
  [self.window bringSubviewToFront:self.topButton];
}

- (void)togglePort
{
  self.port = [self.port  isEqual: @"8081"] ? @"8082" : @"8081";
}

- (void)buttonTapped:(UIButton *)sender
{
  self.reactNativeFactory = nil;
  [self togglePort];
  [self startReactNative];
}

- (NSDictionary *)prepareInitialProps
{
  NSMutableDictionary *initProps = [NSMutableDictionary new];

  NSString *_routeUri = [[NSUserDefaults standardUserDefaults] stringForKey:@"route"];
  if (_routeUri) {
    initProps[@"exampleFromAppetizeParams"] = [NSString stringWithFormat:@"rntester://example/%Example", _routeUri];
  }

  return initProps;
}

- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
{
  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:kBundlePath];
}

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options
{
  return [RCTLinkingManager application:app openURL:url options:options];
}

- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:(const std::string &)name
                                                      jsInvoker:(std::shared_ptr<facebook::react::CallInvoker>)jsInvoker
{
  if (name == facebook::react::NativeCxxModuleExample::kModuleName) {
    return std::make_shared<facebook::react::NativeCxxModuleExample>(jsInvoker);
  }

  return [super getTurboModule:name jsInvoker:jsInvoker];
}

// Required for the remoteNotificationsRegistered event.
- (void)application:(__unused UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
  [RCTPushNotificationManager didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

// Required for the remoteNotificationRegistrationError event.
- (void)application:(__unused UIApplication *)application
    didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
{
  [RCTPushNotificationManager didFailToRegisterForRemoteNotificationsWithError:error];
}

#pragma mark - UNUserNotificationCenterDelegate

// Required for the remoteNotificationReceived and localNotificationReceived events
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler
{
  [RCTPushNotificationManager didReceiveNotification:notification];
  completionHandler(UNNotificationPresentationOptionNone);
}

// Required for the remoteNotificationReceived and localNotificationReceived events
// Called when a notification is tapped from background. (Foreground notification will not be shown per
// the presentation option selected above).
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
    didReceiveNotificationResponse:(UNNotificationResponse *)response
             withCompletionHandler:(void (^)(void))completionHandler
{
  UNNotification *notification = response.notification;

  // This condition will be true if tapping the notification launched the app.
  if ([response.actionIdentifier isEqualToString:UNNotificationDefaultActionIdentifier]) {
    // This can be retrieved with getInitialNotification.
    [RCTPushNotificationManager setInitialNotification:notification];
  }

  [RCTPushNotificationManager didReceiveNotification:notification];
  completionHandler();
}

#pragma mark - New Arch Enabled settings

- (BOOL)bridgelessEnabled
{
  return YES;
}

#pragma mark - RCTComponentViewFactoryComponentProvider

#ifndef RN_DISABLE_OSS_PLUGIN_HEADER
- (nonnull NSDictionary<NSString *, Class<RCTComponentViewProtocol>> *)thirdPartyFabricComponents
{
  NSMutableDictionary *dict = [super thirdPartyFabricComponents].mutableCopy;
  if (!dict[@"RNTMyNativeView"]) {
    dict[@"RNTMyNativeView"] = NSClassFromString(@"RNTMyNativeViewComponentView");
  }
  if (!dict[@"SampleNativeComponent"]) {
    dict[@"SampleNativeComponent"] = NSClassFromString(@"RCTSampleNativeComponentComponentView");
  }
  return dict;
}
#endif

- (NSURL *)bundleURL
{
  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:kBundlePath];
}

end
```

`AppDelegate.h`

```objc
#import <RCTDefaultReactNativeFactoryDelegate.h>
#import <RCTReactNativeFactory.h>
#import <UIKit/UIKit.h>

interface AppDelegate : RCTDefaultReactNativeFactoryDelegate <UIApplicationDelegate>

property (nonatomic, strong, nonnull) UIWindow *window;
property (nonatomic, strong, nonnull) RCTReactNativeFactory *reactNativeFactory;
property (nonatomic, strong, nullable) UIButton *topButton;
property (nonatomic, strong) NSDictionary *launchOptions;
property (nonatomic, assign) NSString *port;

end
```
</details>

Differential Revision: D84058022

Pulled By: coado

Author: coado

packages/react-native/Libraries/AppDelegate/RCTReactNativeFactory.h

@@ -24,6 +24,7 @@
 @class RCTBridge;
 @protocol RCTComponentViewProtocol;
 @class RCTSurfacePresenterBridgeAdapter;
+@class RCTCustomBundleConfiguration;
 @class RCTDevMenuConfiguration;
 
 NS_ASSUME_NONNULL_BEGIN
@@ -117,6 +118,8 @@ typedef NS_ENUM(NSInteger, RCTReleaseLevel) { Canary, Experimental, Stable };
 
 @property (nonatomic, weak) id<RCTReactNativeFactoryDelegate> delegate;
 
+@property (nonatomic, nullable) RCTCustomBundleConfiguration *customBundleConfiguration;
+
 @property (nonatomic, nullable) RCTDevMenuConfiguration *devMenuConfiguration;
 
 @end

packages/react-native/Libraries/AppDelegate/RCTReactNativeFactory.mm

@@ -6,6 +6,7 @@
  */
 
 #import "RCTReactNativeFactory.h"
+#import <React/RCTBundleManager.h>
 #import <React/RCTColorSpaceUtils.h>
 #import <React/RCTDevMenu.h>
 #import <React/RCTLog.h>
@@ -59,6 +60,8 @@ - (instancetype)initWithDelegate:(id<RCTReactNativeFactoryDelegate>)delegate rel
     self.rootViewFactory = [self createRCTRootViewFactory];
 
     [RCTComponentViewFactory currentComponentViewFactory].thirdPartyFabricComponentsProvider = self;
+
+    self.customBundleConfiguration = [RCTCustomBundleConfiguration new];
   }
 
   return self;
@@ -84,6 +87,7 @@ - (void)startReactNativeWithModuleName:(NSString *)moduleName
   UIView *rootView = [self.rootViewFactory viewWithModuleName:moduleName
                                             initialProperties:initialProperties
                                                 launchOptions:launchOptions
+                                    customBundleConfiguration:self.customBundleConfiguration
                                          devMenuConfiguration:self.devMenuConfiguration];
   UIViewController *rootViewController = [_delegate createRootViewController];
   [_delegate setRootView:rootView toRootViewController:rootViewController];

packages/react-native/Libraries/AppDelegate/RCTRootViewFactory.h

@@ -18,6 +18,7 @@
 @class RCTHost;
 @class RCTRootView;
 @class RCTSurfacePresenterBridgeAdapter;
+@class RCTCustomBundleConfiguration;
 @class RCTDevMenuConfiguration;
 
 NS_ASSUME_NONNULL_BEGIN
@@ -202,11 +203,13 @@ typedef void (^RCTLoadSourceForBridgeBlock)(RCTBridge *bridge, RCTSourceLoadBloc
  * @parameter: moduleName  - the name of the app, used by Metro to resolve the module.
  * @parameter: initialProperties  -  a set of initial properties.
  * @parameter: launchOptions  - a dictionary with a set of options.
+ * @parameter: customBundleConfiguration  - a configuration for custom bundle source URL.
  * @parameter: devMenuConfiguration - a configuration for enabling/disabling dev menu.
  */
 - (UIView *_Nonnull)viewWithModuleName:(NSString *)moduleName
                      initialProperties:(NSDictionary *__nullable)initialProperties
                          launchOptions:(NSDictionary *__nullable)launchOptions
+             customBundleConfiguration:(RCTCustomBundleConfiguration *__nullable)customBundleConfiguration
                   devMenuConfiguration:(RCTDevMenuConfiguration *__nullable)devMenuConfiguration;
 
 - (UIView *_Nonnull)viewWithModuleName:(NSString *)moduleName
@@ -226,15 +229,18 @@ typedef void (^RCTLoadSourceForBridgeBlock)(RCTBridge *bridge, RCTSourceLoadBloc
  * Use it to speed up later viewWithModuleName: calls.
  *
  * @parameter: launchOptions  - a dictionary with a set of options.
+ * @parameter: customBundleConfiguration  - a configuration for custom bundle source URL.
  * @parameter: devMenuConfiguration - a configuration for enabling/disabling dev menu.
  */
 - (void)initializeReactHostWithLaunchOptions:(NSDictionary *__nullable)launchOptions
+                   customBundleConfiguration:(RCTCustomBundleConfiguration *__nullable)customBundleConfiguration
                         devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration;
 
-- (RCTHost *)createReactHost:(NSDictionary *__nullable)launchOptions;
-
 - (RCTHost *)createReactHost:(NSDictionary *__nullable)launchOptions
-        devMenuConfiguration:(RCTDevMenuConfiguration *__nullable)devMenuConfiguration;
+    customBundleConfiguration:(RCTCustomBundleConfiguration *__nullable)customBundleConfiguration
+         devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration;
+
+- (RCTHost *)createReactHost:(NSDictionary *__nullable)launchOptions;
 
 @end
 

packages/react-native/Libraries/AppDelegate/RCTRootViewFactory.mm

@@ -21,7 +21,6 @@
 #else
 #import <React/CoreModulesPlugins.h>
 #endif
-#import <React/RCTBundleURLProvider.h>
 #import <React/RCTComponentViewFactory.h>
 #import <React/RCTComponentViewProtocol.h>
 #import <React/RCTFabricSurface.h>
@@ -137,6 +136,7 @@ - (UIView *)viewWithModuleName:(NSString *)moduleName initialProperties:(NSDicti
   return [self viewWithModuleName:moduleName
                 initialProperties:initialProperties
                     launchOptions:nil
+        customBundleConfiguration:[RCTCustomBundleConfiguration new]
              devMenuConfiguration:[RCTDevMenuConfiguration defaultConfiguration]];
 }
 
@@ -145,17 +145,21 @@ - (UIView *)viewWithModuleName:(NSString *)moduleName
   return [self viewWithModuleName:moduleName
                 initialProperties:nil
                     launchOptions:nil
+        customBundleConfiguration:[RCTCustomBundleConfiguration new]
              devMenuConfiguration:[RCTDevMenuConfiguration defaultConfiguration]];
 }
 
 - (void)initializeReactHostWithLaunchOptions:(NSDictionary *)launchOptions
+                   customBundleConfiguration:(RCTCustomBundleConfiguration *)customBundleConfiguration
                         devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration
 {
   // Enable TurboModule interop by default in Bridgeless mode
   RCTEnableTurboModuleInterop(YES);
   RCTEnableTurboModuleInteropBridgeProxy(YES);
 
-  [self createReactHostIfNeeded:launchOptions devMenuConfiguration:devMenuConfiguration];
+  [self createReactHostIfNeeded:launchOptions
+      customBundleConfiguration:customBundleConfiguration
+           devMenuConfiguration:devMenuConfiguration];
   return;
 }
 
@@ -166,15 +170,19 @@ - (UIView *)viewWithModuleName:(NSString *)moduleName
   return [self viewWithModuleName:moduleName
                 initialProperties:initialProperties
                     launchOptions:launchOptions
+        customBundleConfiguration:[RCTCustomBundleConfiguration new]
              devMenuConfiguration:[RCTDevMenuConfiguration defaultConfiguration]];
 }
 
 - (UIView *)viewWithModuleName:(NSString *)moduleName
              initialProperties:(NSDictionary *)initProps
                  launchOptions:(NSDictionary *)launchOptions
+     customBundleConfiguration:(RCTCustomBundleConfiguration *)customBundleConfiguration
           devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration
 {
-  [self initializeReactHostWithLaunchOptions:launchOptions devMenuConfiguration:devMenuConfiguration];
+  [self initializeReactHostWithLaunchOptions:launchOptions
+                   customBundleConfiguration:customBundleConfiguration
+                        devMenuConfiguration:devMenuConfiguration];
 
   RCTFabricSurface *surface = [self.reactHost createSurfaceWithModuleName:moduleName
                                                         initialProperties:initProps ? initProps : @{}];
@@ -245,21 +253,28 @@ - (void)createBridgeAdapterIfNeeded
 #pragma mark - New Arch Utilities
 
 - (void)createReactHostIfNeeded:(NSDictionary *)launchOptions
+      customBundleConfiguration:(RCTCustomBundleConfiguration *)customBundleConfiguration
            devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration
 {
   if (self.reactHost) {
     return;
   }
-  self.reactHost = [self createReactHost:launchOptions devMenuConfiguration:devMenuConfiguration];
+
+  self.reactHost = [self createReactHost:launchOptions
+               customBundleConfiguration:customBundleConfiguration
+                    devMenuConfiguration:devMenuConfiguration];
 }
 
 - (RCTHost *)createReactHost:(NSDictionary *)launchOptions
 {
-  return [self createReactHost:launchOptions devMenuConfiguration:[RCTDevMenuConfiguration defaultConfiguration]];
+  return [self createReactHost:launchOptions
+      customBundleConfiguration:[RCTCustomBundleConfiguration new]
+           devMenuConfiguration:[RCTDevMenuConfiguration defaultConfiguration]];
 }
 
 - (RCTHost *)createReactHost:(NSDictionary *)launchOptions
-        devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration
+    customBundleConfiguration:(RCTCustomBundleConfiguration *)customBundleConfiguration
+         devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration
 {
   __weak __typeof(self) weakSelf = self;
   RCTHost *reactHost =
@@ -270,6 +285,7 @@ - (RCTHost *)createReactHost:(NSDictionary *)launchOptions
                                   return [weakSelf createJSRuntimeFactory];
                                 }
                                    launchOptions:launchOptions
+                       customBundleConfiguration:customBundleConfiguration
                             devMenuConfiguration:devMenuConfiguration];
   [reactHost setBundleURLProvider:^NSURL *() {
     return [weakSelf bundleURL];

packages/react-native/React/Base/RCTBundleManager.h

@@ -9,19 +9,66 @@
 
 @class RCTBridge;
 
-typedef NSURL * (^RCTBridgelessBundleURLGetter)(void);
-typedef void (^RCTBridgelessBundleURLSetter)(NSURL *bundleURL);
+typedef NSURL *_Nullable (^RCTBridgelessBundleURLGetter)(void);
+typedef void (^RCTBridgelessBundleURLSetter)(NSURL *_Nullable bundleURL);
+typedef NSMutableArray<NSURLQueryItem *> *_Nullable (^RCTPackagerOptionsUpdater)(
+    NSMutableArray<NSURLQueryItem *> *_Nullable options);
+
+/**
+ * Configuration class for setting up custom bundle locations
+ */
+@interface RCTCustomBundleConfiguration : NSObject
+
+/**
+ * The URL of the bundle to load from the file system
+ */
+@property (nonatomic, readonly, nullable) NSURL *bundleFilePath;
+
+/**
+ * The server scheme (e.g. http or https) to use when loading from the packager
+ */
+@property (nonatomic, readonly, nullable) NSString *packagerServerScheme;
+
+/**
+ * The server host (e.g. localhost) to use when loading from the packager
+ */
+@property (nonatomic, readonly, nullable) NSString *packagerServerHost;
+
+/**
+ * A block that modifies the packager options when loading from the packager
+ */
+@property (nonatomic, copy, nullable) RCTPackagerOptionsUpdater packagerOptionsUpdater;
+
+/**
+ * The relative path to the bundle.
+ */
+@property (nonatomic, readonly, nullable) NSString *bundlePath;
+
+- (nonnull instancetype)initWithBundleFilePath:(nullable NSURL *)bundleFilePath;
+
+- (nonnull instancetype)initWithPackagerServerScheme:(nullable NSString *)packagerServerScheme
+                                  packagerServerHost:(nullable NSString *)packagerServerHost
+                                          bundlePath:(nullable NSString *)bundlePath;
+
+- (nullable NSURL *)getBundleURL:(NSURL *_Nullable (^_Nullable)(void))fallbackURLProvider;
+
+- (nullable NSString *)getPackagerServerScheme;
+
+- (nullable NSString *)getPackagerServerHost;
+
+@end
 
 /**
  * A class that allows NativeModules/TurboModules to read/write the bundleURL, with or without the bridge.
  */
 @interface RCTBundleManager : NSObject
 #ifndef RCT_REMOVE_LEGACY_ARCH
-- (void)setBridge:(RCTBridge *)bridge;
+- (void)setBridge:(nullable RCTBridge *)bridge;
 #endif // RCT_REMOVE_LEGACY_ARCH
-- (void)setBridgelessBundleURLGetter:(RCTBridgelessBundleURLGetter)getter
-                           andSetter:(RCTBridgelessBundleURLSetter)setter
-                    andDefaultGetter:(RCTBridgelessBundleURLGetter)defaultGetter;
+- (void)setBridgelessBundleURLGetter:(nullable RCTBridgelessBundleURLGetter)getter
+                           andSetter:(nullable RCTBridgelessBundleURLSetter)setter
+                    andDefaultGetter:(nullable RCTBridgelessBundleURLGetter)defaultGetter;
 - (void)resetBundleURL;
-@property NSURL *bundleURL;
+@property (nonatomic, nullable) NSURL *bundleURL;
+@property (nonatomic, nullable) RCTCustomBundleConfiguration *customBundleConfig;
 @end

packages/react-native/React/Base/RCTBundleManager.m

@@ -6,9 +6,94 @@
  */
 
 #import "RCTBundleManager.h"
+#import <React/RCTBundleURLProvider.h>
 #import "RCTAssert.h"
 #import "RCTBridge+Private.h"
 #import "RCTBridge.h"
+#import "RCTLog.h"
+
+@implementation RCTCustomBundleConfiguration
+
+- (instancetype)initWithBundleFilePath:(NSURL *)bundleFilePath
+{
+  return [self initWithBundleFilePath:bundleFilePath packagerServerScheme:nil packagerServerHost:nil bundlePath:nil];
+}
+
+- (instancetype)initWithPackagerServerScheme:(NSString *)packagerServerScheme
+                          packagerServerHost:(NSString *)packagerServerHost
+                                  bundlePath:(NSString *)bundlePath
+{
+  return [self initWithBundleFilePath:nil
+                 packagerServerScheme:packagerServerScheme
+                   packagerServerHost:packagerServerHost
+                           bundlePath:bundlePath];
+}
+
+- (instancetype)initWithBundleFilePath:(NSURL *)bundleFilePath
+                  packagerServerScheme:(NSString *)packagerServerScheme
+                    packagerServerHost:(NSString *)packagerServerHost
+                            bundlePath:(NSString *)bundlePath
+{
+  if (self = [super init]) {
+    _bundleFilePath = bundleFilePath;
+    _packagerServerScheme = packagerServerScheme;
+    _packagerServerHost = packagerServerHost;
+    _bundlePath = bundlePath;
+    _packagerOptionsUpdater = ^NSMutableArray<NSURLQueryItem *> *(NSMutableArray<NSURLQueryItem *> *options)
+    {
+      return options;
+    };
+  }
+
+  return self;
+}
+
+- (NSString *)getPackagerServerScheme
+{
+  if (!_packagerServerScheme) {
+    return [[RCTBundleURLProvider sharedSettings] packagerScheme];
+  }
+
+  return _packagerServerScheme;
+}
+
+- (NSString *)getPackagerServerHost
+{
+  if (!_packagerServerHost) {
+    return [[RCTBundleURLProvider sharedSettings] packagerServerHostPort];
+  }
+
+  return _packagerServerHost;
+}
+
+- (NSURL *)getBundleURL:(NSURL * (^)(void))fallbackURLProvider
+{
+  if (_packagerServerScheme && _packagerServerHost) {
+    NSArray<NSURLQueryItem *> *jsBundleURLQuery =
+        [[RCTBundleURLProvider sharedSettings] createJSBundleURLQuery:_packagerServerHost
+                                                       packagerScheme:_packagerServerScheme];
+
+    NSArray<NSURLQueryItem *> *updatedBundleURLQuery = _packagerOptionsUpdater((NSMutableArray *)jsBundleURLQuery);
+    NSString *path = [NSString stringWithFormat:@"/%@.bundle", _bundlePath];
+    return [[RCTBundleURLProvider class] resourceURLForResourcePath:path
+                                                       packagerHost:_packagerServerHost
+                                                             scheme:_packagerServerScheme
+                                                         queryItems:updatedBundleURLQuery];
+  }
+
+  if (_bundleFilePath) {
+    if (!_bundleFilePath.fileURL) {
+      RCTLogError(@"Bundle file path must be a file URL");
+      return nil;
+    }
+
+    return _bundleFilePath;
+  }
+
+  return fallbackURLProvider();
+}
+
+@end
 
 @implementation RCTBundleManager {
 #ifndef RCT_REMOVE_LEGACY_ARCH
@@ -18,6 +103,7 @@ @implementation RCTBundleManager {
   RCTBridgelessBundleURLSetter _bridgelessBundleURLSetter;
   RCTBridgelessBundleURLGetter _bridgelessBundleURLDefaultGetter;
 }
+@synthesize customBundleConfig;
 
 #ifndef RCT_REMOVE_LEGACY_ARCH
 - (void)setBridge:(RCTBridge *)bridge

packages/react-native/React/Base/RCTBundleURLProvider.h

@@ -97,6 +97,19 @@ NS_ASSUME_NONNULL_BEGIN
                               resourceExtension:(NSString *)extension
                                   offlineBundle:(NSBundle *)offlineBundle;
 
+- (NSArray<NSURLQueryItem *> *)createJSBundleURLQuery:(NSString *)packagerHost
+                                       packagerScheme:(NSString *__nullable)scheme;
+
++ (NSArray<NSURLQueryItem *> *)createJSBundleURLQuery:(NSString *)packagerHost
+                                       packagerScheme:(NSString *__nullable)scheme
+                                            enableDev:(BOOL)enableDev
+                                   enableMinification:(BOOL)enableMinification
+                                      inlineSourceMap:(BOOL)inlineSourceMap
+                                          modulesOnly:(BOOL)modulesOnly
+                                            runModule:(BOOL)runModule
+                                    additionalOptions:
+                                        (NSDictionary<NSString *, NSString *> *__nullable)additionalOptions;
+
 /**
  * The IP address or hostname of the packager.
  */