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

Summary:
## Summary:

Following the [RFC](react-native-community/discussions-and-proposals#933), this PR introduces a new `RCTBundleConfiguration` 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.

The `RCTBundleConfiguration` 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 `RCTBundleConfiguration` the `Connect to Metro...` message shouldn't be suggested.

## Changelog:

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

Pull Request resolved: #54006

Test Plan: Test plan included in the last diff in the stack.

Reviewed By: cipolleschi

Differential Revision: D84058022

Pulled By: coado

fbshipit-source-id: 62c24ec5c6b089220ef9b78add487dcd65aaac9e

Author: coado

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

@@ -9,19 +9,71 @@
 
 @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 RCTBundleConfiguration : NSObject
+
++ (nonnull instancetype)defaultConfiguration;
+
+/**
+ * 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;
+
+- (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
+
+- (nullable instancetype)initWithBundleConfig:(nullable RCTBundleConfiguration *)bundleConfig;
+
 #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, nonnull) RCTBundleConfiguration *bundleConfig;
 @end

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

@@ -6,9 +6,93 @@
  */
 
 #import "RCTBundleManager.h"
+#import <React/RCTBundleURLProvider.h>
 #import "RCTAssert.h"
 #import "RCTBridge+Private.h"
 #import "RCTBridge.h"
+#import "RCTLog.h"
+
+@implementation RCTBundleConfiguration
+
++ (instancetype)defaultConfiguration
+{
+  return [[self alloc] initWithBundleFilePath:nil packagerServerScheme:nil packagerServerHost:nil bundlePath:nil];
+}
+
+- (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
+{
+  if (_packagerServerScheme && _packagerServerHost) {
+    return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:_bundlePath
+                                                      packagerServerScheme:_packagerServerScheme
+                                                        packagerServerHost:_packagerServerHost
+                                                    packagerOptionsUpdater:_packagerOptionsUpdater];
+  }
+
+  if (_bundleFilePath) {
+    if (!_bundleFilePath.fileURL) {
+      RCTLogError(@"Bundle file path must be a file URL");
+      return nil;
+    }
+
+    return _bundleFilePath;
+  }
+
+  return nil;
+}
+
+@end
 
 @implementation RCTBundleManager {
 #ifndef RCT_REMOVE_LEGACY_ARCH
@@ -19,6 +103,20 @@ @implementation RCTBundleManager {
   RCTBridgelessBundleURLGetter _bridgelessBundleURLDefaultGetter;
 }
 
+- (instancetype)initWithBundleConfig:(RCTBundleConfiguration *)bundleConfig
+{
+  if (self = [super init]) {
+    self.bundleConfig = bundleConfig ? bundleConfig : [RCTBundleConfiguration defaultConfiguration];
+  }
+
+  return self;
+}
+
+- (instancetype)init
+{
+  return [self initWithBundleConfig:[RCTBundleConfiguration defaultConfiguration]];
+}
+
 #ifndef RCT_REMOVE_LEGACY_ARCH
 - (void)setBridge:(RCTBridge *)bridge
 {

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

@@ -7,6 +7,7 @@
 
 #import <Foundation/Foundation.h>
 
+#import "RCTBundleManager.h"
 #import "RCTDefines.h"
 
 RCT_EXTERN NSString *_Nonnull const RCTBundleURLProviderUpdatedNotification;
@@ -88,6 +89,16 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (NSURL *__nullable)jsBundleURLForFallbackExtension:(NSString *__nullable)extension;
 
+/**
+ * Returns the jsBundleURL for a given bundle entrypoint,
+ * the packager scheme, server host and options updater
+ * for modifying default packager options.
+ */
+- (NSURL *__nullable)jsBundleURLForBundleRoot:(NSString *)bundleRoot
+                         packagerServerScheme:(NSString *)packagerServerScheme
+                           packagerServerHost:(NSString *)packagerServerHost
+                       packagerOptionsUpdater:(RCTPackagerOptionsUpdater)packagerOptionsUpdater;
+
 /**
  * Returns the resourceURL for a given bundle entrypoint and
  * the fallback offline resource file if the packager is not running.
@@ -97,6 +108,19 @@ NS_ASSUME_NONNULL_BEGIN
                               resourceExtension:(NSString *)extension
                                   offlineBundle:(NSBundle *)offlineBundle;
 
+/**
+ * Returns the query items for given options used to create the jsBundleURL.
+ */
++ (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.
  */

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

@@ -313,6 +313,54 @@ + (NSURL *__nullable)jsBundleURLForBundleRoot:(NSString *)bundleRoot
                             additionalOptions:(NSDictionary<NSString *, NSString *> *__nullable)additionalOptions
 {
   NSString *path = [NSString stringWithFormat:@"/%@.bundle", bundleRoot];
+  NSArray<NSURLQueryItem *> *queryItems = [self createJSBundleURLQuery:packagerHost
+                                                        packagerScheme:scheme
+                                                             enableDev:enableDev
+                                                    enableMinification:enableMinification
+                                                       inlineSourceMap:inlineSourceMap
+                                                           modulesOnly:modulesOnly
+                                                             runModule:runModule
+                                                     additionalOptions:additionalOptions];
+
+  return [RCTBundleURLProvider resourceURLForResourcePath:path
+                                             packagerHost:packagerHost
+                                                   scheme:scheme
+                                               queryItems:[queryItems copy]];
+}
+
+- (NSURL *)jsBundleURLForBundleRoot:(NSString *)bundleRoot
+               packagerServerScheme:(NSString *)packagerServerScheme
+                 packagerServerHost:(NSString *)packagerServerHost
+             packagerOptionsUpdater:(RCTPackagerOptionsUpdater)packagerOptionsUpdater
+{
+  NSArray<NSURLQueryItem *> *queryItems = [RCTBundleURLProvider createJSBundleURLQuery:packagerServerHost
+                                                                        packagerScheme:packagerServerScheme
+                                                                             enableDev:[self enableDev]
+                                                                    enableMinification:[self enableMinification]
+                                                                       inlineSourceMap:[self inlineSourceMap]
+                                                                           modulesOnly:NO
+                                                                             runModule:YES
+                                                                     additionalOptions:nil];
+
+  NSArray<NSURLQueryItem *> *updatedQueryItems = packagerOptionsUpdater((NSMutableArray *)queryItems);
+  NSString *path = [NSString stringWithFormat:@"/%@.bundle", bundleRoot];
+
+  return [RCTBundleURLProvider resourceURLForResourcePath:path
+                                             packagerHost:packagerServerHost
+                                                   scheme:packagerServerScheme
+                                               queryItems:updatedQueryItems];
+}
+
++ (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
+{
   BOOL lazy = enableDev;
   NSMutableArray<NSURLQueryItem *> *queryItems = [[NSMutableArray alloc] initWithArray:@[
     [[NSURLQueryItem alloc] initWithName:@"platform" value:RCTPlatformName],
@@ -345,10 +393,7 @@ + (NSURL *__nullable)jsBundleURLForBundleRoot:(NSString *)bundleRoot
     }
   }
 
-  return [[self class] resourceURLForResourcePath:path
-                                     packagerHost:packagerHost
-                                           scheme:scheme
-                                       queryItems:[queryItems copy]];
+  return queryItems;
 }
 
 + (NSURL *)resourceURLForResourcePath:(NSString *)path