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

* feat(ios): support bundled JS in debug builds

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

* feat(ios): enable development loading view configuration in debug mode

- 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.

* fix(cli): resolve packaged framework without scheme

* fix(ios): make swift tests self-contained

* fix: ftm issue

* fix(ios): address pr review follow-ups

* fix(expo): sync brownfield framework target updates

* refactor(ios): make bundle URL resolver a class

* fix: code review

* fix(ios): address follow-up review comments

* fix: merge conflict

Author: adamTrz

.changeset/tender-poems-rhyme.md

@@ -0,0 +1,5 @@
+---
+'@callstack/react-native-brownfield': minor
+---
+
+Add an opt-in iOS Debug mode for loading the embedded JavaScript bundle with `preferEmbeddedBundleInDebug`, fix `bundleURLOverride` fallback behavior when the override returns `nil`, and add native bundle-resolution tests.

.github/workflows/ci.yml

@@ -92,6 +92,25 @@ jobs:
         run: |
           yarn workspace @callstack/react-native-brownfield brownfield --version
 
+  ios-native-tests:
+    name: iOS native tests
+    runs-on: macos-26
+    needs: build-lint
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Run Swift bundle resolver tests
+        run: |
+          cd packages/react-native-brownfield/ios/swiftpm
+          mkdir -p "$RUNNER_TEMP/swift-home" "$RUNNER_TEMP/swift-cache/clang" "$RUNNER_TEMP/swift-cache/swiftpm"
+          HOME="$RUNNER_TEMP/swift-home" \
+          CLANG_MODULE_CACHE_PATH="$RUNNER_TEMP/swift-cache/clang" \
+          swift test --scratch-path "$RUNNER_TEMP/swift-cache/swiftpm"
+
   android-androidapp-expo:
     name: Android road test (AndroidApp - Expo ${{ matrix.version }})
     runs-on: ubuntu-latest

.gitignore

@@ -82,8 +82,10 @@ secring.gpg
 
 # Typescript
 **/*.tsbuildinfo
+packages/react-native-brownfield/ios/.build/
+packages/react-native-brownfield/ios/swiftpm/.build/
 
 # skillgym
 .skillgym-results/
 
-.cursor
+.cursor

apps/AppleApp/Brownfield Apple App/BrownfieldAppleApp.swift

@@ -90,6 +90,7 @@ struct BrownfieldAppleApp: App {
 
     init() {
         ReactNativeBrownfield.shared.bundle = ReactNativeBundle
+        ReactNativeBrownfield.shared.preferEmbeddedBundleInDebug = true
         ReactNativeBrownfield.shared.startReactNative {
             print("React Native has been loaded")
         }

apps/AppleApp/Brownfield Apple App/components/ContentView.swift

@@ -19,12 +19,12 @@ struct ContentView: View {
         NavigationView {
 
             VStack(spacing: 16) {
-                GreetingCard(name: "iOS Expo")
+                GreetingCard(name: "iOS Vanilla")
 
                 MessagesView()
 
                 ReactNativeView(
-                    moduleName: "main",
+                    moduleName: "RNApp",
                     initialProperties: [
                         "nativeOsVersionLabel":
                             "\(UIDevice.current.systemName) \(UIDevice.current.systemVersion)"

docs/docs/docs/api-reference/react-native-brownfield/objective-c.mdx

@@ -33,6 +33,7 @@ A singleton that keeps an instance of `ReactNativeBrownfield` object.
 | `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.                                                  |
+| `preferEmbeddedBundleInDebug` | `BOOL` | `NO` | Prefer the embedded JavaScript bundle instead of Metro when the framework is built in Debug. |
 | `bundleURLOverride` | `NSURL *(^)(void)` | `nil`           | Dynamic bundle URL provider called on every bundle load. When set, overrides default bundle load behavior. |
 
 ---

docs/docs/docs/api-reference/react-native-brownfield/swift.mdx

@@ -33,6 +33,7 @@ ReactNativeBrownfield.shared
 | `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.                                      |
+| `preferEmbeddedBundleInDebug` | `Bool` | `false` | Prefer the embedded JavaScript bundle instead of Metro when the framework is built in Debug. |
 | `bundleURLOverride` | `(() -> URL?)?` | `nil`           | Dynamic bundle URL provider called on every bundle load. When set, overrides default behavior. |
 
 ---

docs/docs/docs/getting-started/expo.mdx

@@ -138,6 +138,14 @@ struct IosApp: App {
 }
 ```
 
+If you package the framework in **Debug** and want to run it without Metro, enable the embedded bundle explicitly before calling `startReactNative`:
+
+```swift
+ReactNativeBrownfield.shared.bundle = ReactNativeBundle
+ReactNativeBrownfield.shared.preferEmbeddedBundleInDebug = true
+ReactNativeBrownfield.shared.startReactNative()
+```
+
 2. Propagate the didFinishLaunchingWithOptions
 
 ```swift

docs/docs/docs/getting-started/ios.mdx

@@ -172,6 +172,16 @@ When running in **Debug**, React Native Brownfield expects a JS dev server runni
 npx react-native start
 ```
 
+## Embedded bundle in Development
+
+If you want to run a **Debug-built** framework without Metro, enable the embedded bundle explicitly before calling `startReactNative`:
+
+```swift
+ReactNativeBrownfield.shared.bundle = ReactNativeBundle
+ReactNativeBrownfield.shared.preferEmbeddedBundleInDebug = true
+ReactNativeBrownfield.shared.startReactNative()
+```
+
 ### Release Configuration
 
 In **Release**, the JS bundle is loaded directly from the XCFramework - no dev server needed.

packages/cli/src/brownfield/commands/packageIos.ts

@@ -27,6 +27,8 @@ import {
 } from '../../shared/index.js';
 import { runBrownieCodegenIfApplicable } from '../../brownie/helpers/runBrownieCodegenIfApplicable.js';
 import { runNavigationCodegenIfApplicable } from '../../navigation/helpers/runNavigationCodegenIfApplicable.js';
+import { copyDebugBundleToSimulatorSlice } from '../utils/copyDebugBundleToSimulatorSlice.js';
+import { resolvePackagedFrameworkName } from '../utils/resolvePackagedFrameworkName.js';
 import { stripFrameworkBinary } from '../utils/stripFrameworkBinary.js';
 
 /** Help text for `--use-prebuilt-rn-core` (keep in sync with docs/docs/docs/getting-started/ios.mdx, "React Native Prebuilts" section). */
@@ -163,6 +165,49 @@ export const packageIosCommand = curryOptions(
         platformConfig
       );
 
+      const productsPath = path.join(options.buildFolder, 'Build', 'Products');
+      const { frameworkName, resolution, candidates } =
+        resolvePackagedFrameworkName({
+          explicitScheme: options.scheme,
+          productsPath,
+          configuration,
+        });
+
+      if (frameworkName) {
+        copyDebugBundleToSimulatorSlice({
+          productsPath,
+          configuration,
+          frameworkName,
+        });
+
+        if (configuration.includes('Debug')) {
+          // Re-merge only Debug frameworks so the simulator slice includes main.jsbundle.
+          await mergeFrameworks({
+            sourceDir: userConfig.project.ios.sourceDir,
+            frameworkPaths: [
+              path.join(
+                productsPath,
+                `${configuration}-iphoneos`,
+                `${frameworkName}.framework`
+              ),
+              path.join(
+                productsPath,
+                `${configuration}-iphonesimulator`,
+                `${frameworkName}.framework`
+              ),
+            ],
+            outputPath: path.join(packageDir, `${frameworkName}.xcframework`),
+          });
+        }
+      } else if (configuration.includes('Debug')) {
+        const debugResolutionMessage =
+          resolution === 'ambiguous'
+            ? `Skipping Debug simulator JS bundle copy: found multiple bundled framework candidates (${candidates?.join(', ') ?? 'none'}); pass --scheme explicitly`
+            : 'Skipping Debug simulator JS bundle copy: could not resolve the packaged framework output automatically; pass --scheme explicitly';
+
+        logger.warn(debugResolutionMessage);
+      }
+
       const reactBrownfieldXcframeworkPath = path.join(
         packageDir,
         'ReactBrownfield.xcframework'
@@ -175,11 +220,6 @@ export const packageIosCommand = curryOptions(
       }
 
       if (hasBrownie) {
-        const productsPath = path.join(
-          options.buildFolder,
-          'Build',
-          'Products'
-        );
         const brownieOutputPath = path.join(packageDir, 'Brownie.xcframework');
 
         await mergeFrameworks({
@@ -212,11 +252,6 @@ export const packageIosCommand = curryOptions(
       }
 
       if (hasNavigation) {
-        const productsPath = path.join(
-          options.buildFolder,
-          'Build',
-          'Products'
-        );
         const brownfieldNavigationOutputPath = path.join(
           packageDir,
           'BrownfieldNavigation.xcframework'