Brownfield with Expo for iOS support

[tlomozik]

Ask your Question

Can RNEF be used together with Expo? I want to do a brownfield integration of an Expo app into a native iOS project. As far as I can tell, the documentation doesn’t explicitly say it’s unsupported. You do have Extra steps for Expo CLI in the Android Brownfield section of the docs. However, in your ebook I found the following statement:

Currently, the most popular way to start a React Native project is through the
Expo framework, which offers the best developer experience. However, Expo
doesn’t support brownfield integrations, so we’ll focus on the Community
Template, as this is what’s referred from the official documentation.

Can you confirm whether it is not possible to create a brownfield integration using RNEF or react-native-brownfield with Expo?

[thymikee]

The ebook is slightly outdated now compared to our docs. You should be able to package an Expo app as a framework, although you won't be able to easily use our package:ios and package:aar commands. Instead, you can customize this script which we link to in the docs: https://github.com/callstackincubator/modern-brownfield-ref/blob/b23641f3ff7c278743d35013841d5494905ba190/package.json#L14

[tlomozik]

I spent quite some time on trying to get it to work with Expo but eventually failed.
I used this script here.
Then, I did what's described here (except installing the @rnef/plugin-brownfield-ios plugin)

During pods installation I get this warning (don't know if it matters):

[!] Can't merge pod_target_xcconfig for pod targets: ["expo-dev-menu", "Main", "ReactNativeCompatibles", "SafeAreaView", "Vendored"]. Singular build setting DEFINES_MODULE has different values.

And after running a script I get this (both debug and release mode):

The following build commands failed:
	SwiftVerifyEmittedModuleInterface normal x86_64 Verifying\ emitted\ module\ interface\ EXDevMenuInterface.private.swiftinterface /Users/user/Code/my-project/ios/build/Build/Intermediates.noindex/Pods.build/Release-iphonesimulator/expo-dev-menu-interface.build/Objects-normal/x86_64/EXDevMenuInterface.private.swiftinterface (in target 'expo-dev-menu-interface' from project 'Pods')
	SwiftVerifyEmittedModuleInterface normal arm64 Verifying\ emitted\ module\ interface\ EXDevMenuInterface.private.swiftinterface /Users/user/Code/my-project/ios/build/Build/Intermediates.noindex/Pods.build/Release-iphonesimulator/expo-dev-menu-interface.build/Objects-normal/arm64/EXDevMenuInterface.private.swiftinterface (in target 'expo-dev-menu-interface' from project 'Pods')
	Building workspace my-project with scheme POTMFramework and configuration Release
(3 failures)
Build failed

Then I tried to exclude expo-dev-menu-interface in Podfile, but it didn't help much.

Any ideas? 😟

[thymikee]

Asked internally, hope someone will have an idea

[hurali97]

Hi @tlomozik 👋

Currently, we have the docs in RNEF updated for Expo support with brownfield integrations for AAR (android). For iOS, there are no docs added for Expo support with brownfield integrations for xcframework (iOS).

I will take a look at this integration over a few days.

[VigneshPandianB25]

@tlomozik add this in your podfile

installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
if target.name == 'yourframework'
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
else
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'NO'
end

[hurali97]

Hi @tlomozik - 👋

I spend some time investigating and generating an xcframework from an expo project. However, I faced the same issue related to swift interface. After some investigations, it turned out that the error is related to how expo manages their modules and using those in a swift based framework.

Then I discarded that progress and created a new objective-c based framework. Then I ran the command to generate the xcframework using the same script you have above, there was a success and no issues related to swift interface.

Next I consumed the xcframework in a swiftUI based iOS App. However, while consuming it, I received an error that no module EXConstants is found.

import RNExpoFramework

The issue here is that expo-modules-autolinking auto-generates ExpoModulesProvider for both the app and the framework. Which is then compiled with the xcframework. In that class, there are statements like import EXConstants and others.

Now, when this framework is used by the iOS App, it can not find the EXConstants since this is a framework internal module. So to fix it, I added a build-script to the framework target, which manually replaces import Ex/* with internal import Ex/*

And finally, we have no more issues and the iOS App would compile and run successfully.

---

However, now comes the complicated part, to show the RN UI inside iOS App. This part can not use the standard RN integration as Expo manages the linking of it's modules separately. So we need to load those modules and also render the RN UI.

Based on my investigations, I am able to load the RN instance, however it looks like that the expo modules are not correctly linked.

I will continue the investigations over the few days and keep us posted here.

Screen.Recording.2025-08-18.at.5.25.41.PM.mov

[hurali97]

Hi All 👋

I managed to spend some time on this and looks like we have a success 🎉 We are able to have Expo running in a swiftUI App.

Screen.Recording.2025-08-18.at.10.01.12.PM.mov

---

However, there are a few gotchas. The ExpoModulesProvider is an auto-generated class and it is used to provide a list of expo modules to be linked and registered by Expo. In ExpoModulesCore/ModuleRegistry there is a function register:

  /**
   Registers modules exported by given modules provider.
   */
  public func register(fromProvider provider: ModulesProviderProtocol) {
      print("==== register \(provider.getModuleClasses().count)====")
    provider.getModuleClasses().forEach { moduleType in
      register(moduleType: moduleType)
    }
  }

This count is always zero and hence we were getting a crash in my previous message. Now, what is strange is that when I run nm -gU RNExpoFramework | grep ExpoModulesProvider I get a list of symbols for ExpoModulesProvider:

000000000151aec0 S _$s13RNEXFramework19ExpoModulesProviderCMo
000000000149f9b8 D _$s13RNEXFramework19ExpoModulesProviderCMs
00000000000041c0 T _$s13RNEXFramework19ExpoModulesProviderCfD
000000000149f9b8 D _OBJC_CLASS_$_ExpoModulesProvider
000000000149f988 D _OBJC_METACLASS_$_ExpoModulesProvider

So it looks like the class is there in the xcframework but for some reasons the getModuleClasses returns an empty list. However, when I try to manually reference this class in ReactNativeHostManager.initialize func, the list is populated and works.

func initialize() {
// other code
let _ = ExpoModulesProvider()
}

---

I would like to spend a few days over this and also clean up how I have done and tested the integrations. I would also like to discuss it internally to get the feedback. Hopefully, this week I can compile docs and share those here as well, so you all can also give it a try.

[tlomozik]

@hurali97 Nice work!!! 🤘

[hurali97]

Hi Everyone 👋

I am sharing the steps to allow the brownfield integration on iOS using Expo. Please give it a try and share the feedback. With Expo SDK 54 on the horizon, some of these steps might change. I will need to take a look at SDK 54 changes, once it is stable and released. We will also see how we want to document these steps on Rock

Create a Framework target in your Expo App

• Go to Xcode -> File -> Target -> Framework
• Select language as Objective-C

• Convert your Framework folder to a group. Follow step 5-6 from here

Add Pod Target and Build Script

• Follow this step to add a Pod Target - here
• Follow this step to add a build script - here
• Next run the pod install using USE_FRAMEWORKS=static npx pod-install.

Add a swift file ReactNativeHostManager

In this step, we will add a file to help with initializing react-native instance with expo and function to load and present RN UI.

internal import React
internal import React_RCTAppDelegate
internal import Expo
internal import ReactAppDependencyProvider
import UIKit


public class ReactNativeHostManager {
  public static let shared = ReactNativeHostManager()
  
  private var reactNativeDelegate: ExpoReactNativeFactoryDelegate?
  private var reactNativeFactory: RCTReactNativeFactory?
  private var expoDelegate: ExpoAppDelegate?
  
  public func initialize() {
    let delegate = ReactNativeDelegate()
    let factory = ExpoReactNativeFactory(delegate: delegate)
    delegate.dependencyProvider = RCTAppDependencyProvider()
    
    reactNativeDelegate = delegate
    reactNativeFactory = factory
    
    expoDelegate = ExpoAppDelegate()
    expoDelegate?.bindReactNativeFactory(factory)

    // required to avoid this being file be stripped by the swift compiler
    let _ = ExpoModulesProvider()
  }
  
// propagate delegate methods to ExpoAppDelegate
  public func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    ((expoDelegate?.application(application, didFinishLaunchingWithOptions: launchOptions)) != nil)
  }
  
// load & present RN UI
  public func loadView(
    moduleName: String, initialProps: [AnyHashable: Any]?,
    launchOptions: [AnyHashable: Any]?
  ) -> UIView {
    return (expoDelegate?.recreateRootView(withBundleURL: nil, moduleName: "main",initialProps: initialProps, launchOptions: launchOptions))!
  }
}

class ReactNativeDelegate: ExpoReactNativeFactoryDelegate {
  // Extension point for config-plugins
  
  override func sourceURL(for bridge: RCTBridge) -> URL? {
    // needed to return the correct URL for expo-dev-client.
    bridge.bundleURL ?? bundleURL()
  }
  
  override func bundleURL() -> URL? {
#if DEBUG
    return RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: ".expo/.virtual-metro-entry")
#else
    return Bundle.main.url(forResource: "main", withExtension: "jsbundle")
#endif
  }
}

Add a build script to patch ExpoModulesProvider

There is an auto-generated swift file ExpoModulesProvider which gets generated for both RN App target and the framework target. What we have to do is to patch this file as part of the build script. So when we are generating the framework, this script will execute and patch the file.

Why this patch? The reason is that it has imports to Expo libraries and when this gets bundled with the xcframework and the App is built, the compiler treats them as those Expo libraries will be available at the App level. However, these are the internal libraries which are built with the xcframework. So to fix it, we have to annotated the internal directive with imports.

Go to your Framework target -> build phases and add a run script as show below:

# Path to ExpoModulesProvider.swift
FILE="${SRCROOT}/Pods/Target Support Files/Pods-expoapptest-RNEXFramework/ExpoModulesProvider.swift"

if [ -f "$FILE" ]; then
  echo "Patching $FILE to hide Expo from public interface"

  # 1. Replace imports with internal imports
  sed -i '' 's/^import EX/internal import EX/' "$FILE"
  
  sed -i '' 's/^import Ex/internal import Ex/' "$FILE"

  # 2. Replace class visibility
  sed -i '' 's/public class ExpoModulesProvider/internal class ExpoModulesProvider/' "$FILE"
fi

Let's Test

• Add the following bash script in your expo-app:

#!/bin/bash
SCRIPT_DIR="./$(dirname "${BASH_SOURCE[0]}")"

trap 'echo "Build interrupted"; exit 1' INT

CDPATH=${CDPATH:-"$SCRIPT_DIR/ios"}
WORKSPACE=${WORKSPACE:-"expoapptest"}
SCHEME=${SCHEME:-"RNEXFramework"}
CONFIGURATION=${CONFIGURATION:-"Debug"}

for arg in "$@"; do
  case $arg in
    --release)
      CONFIGURATION="Release"
      shift
      ;;
  esac
done

cd "$CDPATH" || { echo "Failed to change directory to $CDPATH"; exit 1; }

echo -e "Cleaning the old output... \n"
rm -rf "./$SCHEME.xcframework"

mkdir -p ./frameworks/simulator

echo -e "Building $CONFIGURATION frameworks... \n"

xcodebuild \
  -workspace "$WORKSPACE.xcworkspace" \
  -scheme "$SCHEME" \
  -derivedDataPath build \
  -destination "generic/platform=iphonesimulator" \
  -configuration "$CONFIGURATION" \
  SWIFT_VERSION=5.10 \
  SKIP_INSTALL=NO \
  ONLY_ACTIVE_ARCH=NO || { echo "Build failed"; exit 1; }

echo -e "Moving built frameworks... \n"
mv "./build/Build/Products/$CONFIGURATION-iphonesimulator/$SCHEME.framework" ./frameworks/simulator/ || { echo "Failed to move simulator framework"; exit 1; }

echo -e "Creating XCFramework..."
xcodebuild \
  -create-xcframework \
  -framework "./frameworks/simulator/$SCHEME.framework" \
  -output "$SCHEME.xcframework" || { echo "Failed to create XCFramework"; exit 1; }
 
echo -e "Cleaning up temporary files... \n"

echo "Build completed successfully!"

• run the script using sh build-xcframework.sh
• upon success, the xcframework should be generated

• The next step is to consume this framework in an iOS App. Create a new iOS App or use an existing one.
• Link the generated framework to your iOS App. Also link the hermes.xcframework from ios/Pods/hermes-engine/destroot/Library/Frameworks/universal/hermes.xcframework
• One last step is to add UIViewControllerBasedStatusBarAppearance to false in your iOS App's Info.plist file.
• And that is all. You should be able to see your Expo RN App running in your iOS App.

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2025-08-26.at.22.32.28.mp4

Here is the repo if you want to verify the steps: https://github.com/hurali97/expo-brownfield-app/tree/main

cc: @tlomozik @thymikee @atlj

[cudymvl]

@hurali97,

Hi there. I ran into a problem while testing the iOS build, so I opened a new issue with all the details.

Please check Issue #1 when you get a chance: hurali97/expo-brownfield-app#1.

Thanks for your time!