feat(ios): support bundled JS in debug builds by adamTrz · Pull Request #317 · callstack/react-native-brownfield

adamTrz · 2026-05-08T12:25:01Z

Summary

Fixes iOS Debug packaged-bundle loading for brownfield apps running without Metro.

This PR addresses the case where a consumed brownfield XCFramework is built in Debug and the host app wants to load the packaged JavaScript bundle instead of relying on a dev server.

Root cause

There were two separate issues:

Runtime resolution

in Debug, the iOS runtime always preferred Metro and ignored the embedded main.jsbundle

Packaging

even after adding a runtime opt-in for bundled JS in Debug, the simulator slice of the packaged BrownfieldLib.xcframework did not contain main.jsbundle
React Native skips bundling for Debug simulator builds by default, so the packaged simulator artifact was not self-sufficient

What changed

Runtime

adds preferBundledBundleInDebug to ReactNativeBrownfield
extracts bundle URL selection into a small testable resolver
keeps current Debug behavior unchanged by default
when preferBundledBundleInDebug = true, Debug builds load the embedded bundle
fixes bundleURLOverride fallback behavior when the override returns nil

Packaging

after Debug iOS packaging, copies main.jsbundle from the device framework build product into the simulator framework build product
re-merges BrownfieldLib.xcframework so the simulator slice also contains main.jsbundle
keeps DX simple:
- no new CLI flags
- no extra Xcode env vars
- no special simulator packaging flow

Validation / coverage

documents the new opt-in in iOS / Expo docs
adds native Swift tests for iOS bundle URL resolution
adds CLI tests for Debug simulator bundle copying
adds a generic iOS native tests CI job for Swift-based iOS tests

Repro note

This issue only reproduces when the consumed XCFrameworks are themselves built in Debug.

A Debug host app linked against Release-built XCFrameworks is a false negative, because the framework runtime has already been compiled without the Debug Metro branch.

Validation

swift test in packages/react-native-brownfield/ios
yarn workspace @callstack/brownfield-cli test src/brownfield/utils/__tests__/copy-debug-bundle-to-simulator-slice.test.ts
yarn exec brownfield package:ios --scheme BrownfieldLib --configuration Debug
verified that:
- Debug-iphonesimulator/BrownfieldLib.framework/main.jsbundle exists
- BrownfieldLib.xcframework/ios-arm64_x86_64-simulator/BrownfieldLib.framework/main.jsbundle exists
manual repro flow with Debug-built XCFrameworks and Metro stopped

User impact

Host apps can now explicitly opt into running a Debug-built brownfield framework from the packaged bundle:

ReactNativeBrownfield.shared.bundle = ReactNativeBundle
ReactNativeBrownfield.shared.preferBundledBundleInDebug = true
ReactNativeBrownfield.shared.startReactNative()

With the normal Debug packaging flow, the packaged simulator XCFramework now includes the bundle needed for that opt-in to work without Metro.

- Added a method to configure the development loading view based on the debug settings. - Introduced `BrownfieldDevLoadingViewBridge` to manage the loading view state. - Updated `BrownfieldAppleApp` to prefer bundled bundles in debug mode. - Adjusted `ExpoHostRuntime` and `ReactNativeHostRuntime` to call the new configuration method.

artus9033

Amazing work! Left some comments for naming conventions & few questions, LGTM after they are resolved.

artus9033 · 2026-05-12T07:20:22Z

 | `entryFile`         | `NSString`         | `index`         | Path to JavaScript entry file in development.                                                              |
 | `bundlePath`        | `NSString`         | `main.jsbundle` | Path to JavaScript bundle file.                                                                            |
 | `bundle`            | `NSBundle`         | `Bundle.main`   | Bundle instance to lookup the JavaScript bundle resource.                                                  |
+| `preferBundledBundleInDebug` | `BOOL` | `NO` | Prefer the embedded JavaScript bundle instead of Metro when the framework is built in Debug. |


It's a bit of a tongue twister ;) let's rename this to preferEmbeddedBundleInDebug

artus9033 · 2026-05-12T07:20:28Z

 | `entryFile`         | `String`        | `index`         | Path to JavaScript entry file in development.                                                  |
 | `bundlePath`        | `String`        | `main.jsbundle` | Path to JavaScript bundle file.                                                                |
 | `bundle`            | `Bundle`        | `Bundle.main`   | Bundle instance to lookup the JavaScript bundle resource.                                      |
+| `preferBundledBundleInDebug` | `Bool` | `false` | Prefer the embedded JavaScript bundle instead of Metro when the framework is built in Debug. |


artus9033 · 2026-05-12T07:21:01Z

 npx react-native start
 ```

+If you want to run a **Debug-built** framework without Metro, enable the bundled bundle explicitly before calling `startReactNative`:


I'd add a ## Embedded bundle in Development section here

artus9033 · 2026-05-12T07:21:16Z

+interface BrownfieldNavigationDelegate {
+  fun navigateToSettings()
+  fun navigateToReferrals(userId: String)
+}


This is codegen-ed and should not be committed :)

artus9033 · 2026-05-12T07:21:24Z

+  override fun navigateToSettings() {
+    BrownfieldNavigationManager.getDelegate().navigateToSettings()
+  }
+
+  @ReactMethod
+  override fun navigateToReferrals(userId: String) {
+    BrownfieldNavigationManager.getDelegate().navigateToReferrals(userId)


same as above, revert

artus9033 · 2026-05-12T07:25:01Z

@@ -0,0 +1,26 @@
+import Foundation
+
+enum BrownfieldBundleURLResolver {


How about we make that a class?

artus9033 · 2026-05-12T07:26:17Z

+let package = Package(
+  name: "BrownfieldBundleSupport",
+  platforms: [
+    .macOS(.v13),
+  ],


Are you sure we need this here? It may be a tad confusing to look at the ios folder with this macos package def. Can we move it to a subdir?

artus9033 · 2026-05-12T07:26:41Z

+   * Prefer the embedded JavaScript bundle instead of Metro when this framework is built in Debug.
+   * Default value: false
+   */
+  public var preferBundledBundleInDebug: Bool = false {


Rename like above

artus9033 · 2026-05-12T07:26:50Z

  var entryFile = "index"
  var bundlePath = "main.jsbundle"
  var bundle = Bundle.main
+  var preferBundledBundleInDebug = false


Rename like above

artus9033 · 2026-05-12T07:27:41Z

+    DYLIB_INSTALL_NAME_BASE: '"@rpath"',
+    INSTALL_PATH: '"$(LOCAL_LIBRARY_DIR)/Frameworks"',


Won't we need the same in non-Expo (RNC CLI) workflow?

adamTrz added 3 commits May 6, 2026 17:19

feat(ios): support bundled JS in debug builds

f1b5447

fix(cli): embed debug JS bundle in simulator xcframeworks

ff2a8a7

adamTrz requested a review from artus9033 May 8, 2026 13:23

adamTrz added 2 commits May 11, 2026 09:33

fix(cli): resolve packaged framework without scheme

5967c3e

fix(ios): make swift tests self-contained

50e9b91

artus9033 requested changes May 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(ios): support bundled JS in debug builds#317

feat(ios): support bundled JS in debug builds#317
adamTrz wants to merge 5 commits into
mainfrom
adamTrz-ios-debug-bundled-bundle

adamTrz commented May 8, 2026

Uh oh!

artus9033 left a comment

Uh oh!

artus9033 May 12, 2026

Uh oh!

artus9033 May 12, 2026

Uh oh!

artus9033 May 12, 2026

Uh oh!

artus9033 May 12, 2026

Uh oh!

artus9033 May 12, 2026

Uh oh!

artus9033 May 12, 2026

Uh oh!

artus9033 May 12, 2026

Uh oh!

artus9033 May 12, 2026

Uh oh!

artus9033 May 12, 2026

Uh oh!

artus9033 May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,26 @@
		import Foundation

		enum BrownfieldBundleURLResolver {

		DYLIB_INSTALL_NAME_BASE: '"@rpath"',
		INSTALL_PATH: '"$(LOCAL_LIBRARY_DIR)/Frameworks"',

Conversation

adamTrz commented May 8, 2026

Summary

Root cause

What changed

Runtime

Packaging

Validation / coverage

Repro note

Validation

User impact

Uh oh!

artus9033 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants