📱 expo-brownfield

expo-brownfield provides a toolkit and APIs for integrating Expo into existing native applications.

API Documentation

You can find the API documentation for the beta release in the Expo documentation.

Installation in managed Expo projects

For managed Expo projects, please follow the installation instructions in the API documentation for the beta release.

Installation in bare React Native projects

For bare React Native projects, you must ensure that you have installed and configured the expo package before continuing.

Config plugin

Ensure that you have the expo-brownfield plugin included in your app.json or app.config.js file. You can pass additional configurations (such as iOS target name or Android library name) via the plugin options. If no extra options are added, defaults will be used.

{
  "plugins": ["expo-brownfield"]
}

{
  "plugins": [
    [
      "expo-brownfield",
      {
        "ios": {
          "targetName": "MyBrownfield"
        },
        "android": {
          "library": "mybrownfield"
        }
      }
    ]
  ]
}

Configure for Android and iOS

Run npx expo prebuild after adding the plugin to your app.json file to generate the additional native targets for brownfield.

For projects that don't use CNG please follow the manual steps at How to add Expo to an existing native (brownfield) app.

Using Prebuilt modules on iOS

Enable expo-build-properties's ios.usePrecompiledModules so pod install downloads each Expo module as a prebuilt .xcframework instead of building it from source. build:ios automatically detects those xcframeworks in ios/Pods/ and bundles them into the output Swift Package alongside the brownfield framework, React, Hermes, and ReactNativeDependencies.

{
  "plugins": [
    ["expo-build-properties", { "ios": { "usePrecompiledModules": true } }],
    "expo-brownfield"
  ]
}

npx expo prebuild --platform ios
npx expo-brownfield build:ios --release --package MyAppPackage

When precompiled modules are detected, the resulting artifacts/MyAppPackage-release/ directory is a Swift Package with a single aggregate .library product — add it to your host iOS app via Xcode's Add Package Dependencies → Add Local and Xcode will link every bundled .xcframework automatically.

Swift Package Manager has no per-configuration overload for .binaryTarget(path:), so each output package is pinned to the flavor it was built with. Run build:ios once per flavor (e.g. --debug and --release) and distribute the two packages side by side.

Shared SPM dependencies

Several Expo modules link against shared Swift Package dependencies (e.g. expo-image → SDWebImage, libavif). To prevent runtime Library not loaded: @rpath/... crashes in the host app, build:ios looks for each declared SPM dependency in three locations and bundles the first match into the output package:

1. Inside the pod — ios/Pods/<PodName>/<Dep>.xcframework/, when the prebuilt tarball already includes the dep.
2. Inside the published npm package — node_modules/<package>/prebuilds/output/.../<flavor>/xcframeworks/<Dep>.xcframework/. This is the path used by Expo modules published with bundled SPM deps and is the recommended setup for projects outside the Expo monorepo.
3. Shared .spm-deps/ cache — either pointed at by EXPO_PRECOMPILED_MODULES_PATH (e.g. EXPO_PRECOMPILED_MODULES_PATH=/path/to/.build) or auto-discovered at packages/precompile/.build/.spm-deps/ when running inside the Expo monorepo.

If a declared SPM dependency can't be found in any of these locations, build:ios fails with an actionable error rather than shipping a Swift Package that would crash at runtime.

Embedding multiple brownfield frameworks in one host app (iOS)

When two or more Expo brownfield frameworks need to coexist inside the same host iOS app, set multipleFrameworks: true on the iOS plugin config:

{
  "plugins": [
    [
      "expo-brownfield",
      {
        "ios": {
          "targetName": "MyBrownfield",
          "multipleFrameworks": true
        }
      }
    ]
  ]
}

Each brownfield framework gets a unique Swift module name (the framework target name), so its public Swift types are already isolated per-app. Every ObjC class registered by the framework gets a <TargetName>_ prefix via @objc(...), and every ObjC symbol in the pod dependency graph is rewritten with the same prefix at compile time — so two frameworks can ship overlapping pods without duplicate-symbol errors at link time.

The mangling runs as part of pod install via a small Ruby shim and a Node worker bundled with expo-brownfield. The first run after a dependency change rebuilds the symbol set; subsequent pod install invocations are skipped via a dependency-graph checksum.

Contributing

Contributions are very welcome! Please refer to guidelines described in the contributing guide.