Back to Details

expo-brownfield

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Expo Brownfield

Expo Brownfield

A brownfield app is an existing native iOS or Android app that adopts React Native incrementally, as opposed to a greenfield app that is React Native from day one.
Expo supports two distinct ways to add React Native to a brownfield project:
ApproachWhat ships to the native appWhen to choose
IsolatedPrebuilt AAR / XCFrameworkNative team doesn't need Node or RN tooling; RN code can live in a separate repo
IntegratedReact Native sources added to the existing Gradle / CocoaPods buildOne team owns everything; comfortable with RN tooling; wants a single build
For the full decision matrix, see ./references/comparison.md.
brownfield应用是指逐步采用React Native的现有原生iOS或Android应用，与之相对的是greenfield应用——从项目启动之初就完全基于React Native构建。
Expo支持两种将React Native添加到brownfield项目中的方式：
方案类型交付给原生应用的内容适用场景
独立式（Isolated）预构建的AAR / XCFramework原生团队无需Node或RN工具链；RN代码可存放在独立仓库中
集成式（Integrated）将React Native源码添加到现有Gradle / CocoaPods构建流程中由单一团队负责所有代码；熟悉RN工具链；希望采用统一构建流程
完整的决策矩阵请查看 ./references/comparison.md。

Pick an approach

选择合适的方案

Use these quick rules — fall through to 
comparison.md
for anything ambiguous.
  • Choose isolated if the iOS/Android team must consume RN as a regular library dependency (AAR or XCFramework), without installing Node, Yarn, or the React Native build toolchain.
  • Choose isolated if RN code and native code live in separate repositories or release on independent cadences.
  • Choose integrated if a single team owns both the native and RN code and is willing to add React Native + Expo to the native project's Gradle and CocoaPods setup.
  • Choose integrated if you want hot reload and JS source maps to work seamlessly inside the existing native build process.
可遵循以下快速规则——若遇到模糊场景，请参考
comparison.md
。
  • 如果iOS/Android团队必须将RN作为常规库依赖（AAR或XCFramework）使用，且无需安装Node、Yarn或React Native构建工具链，请选择独立式方案。
  • 如果RN代码与原生代码存放在不同仓库，或发布节奏相互独立，请选择独立式方案。
  • 如果由单一团队负责原生代码和RN代码，且愿意将React Native + Expo添加到原生项目的Gradle和CocoaPods配置中，请选择集成式方案。
  • 如果希望热重载和JS源码映射在现有原生构建流程中无缝工作，请选择集成式方案。

References

参考文档

  • ./references/brownfield-isolated.md -- Build RN as AAR/XCFramework and consume from the native app (BrownfieldActivity, ReactNativeViewController, ReactNativeView)
  • ./references/brownfield-integrated.md -- Add RN and Expo directly to existing Gradle and CocoaPods builds (ReactActivity, RCTRootView, Podfile)
  • ./references/comparison.md -- Decision criteria, trade-offs, and scenario mapping for choosing an approach
  • ./references/troubleshooting.md -- Metro connection, build, signing, and module-resolution issues common to both approaches
More information available at https://docs.expo.dev/brownfield/overview/
  • ./references/brownfield-isolated.md -- 将RN构建为AAR/XCFramework并供原生应用调用（BrownfieldActivity、ReactNativeViewController、ReactNativeView）
  • ./references/brownfield-integrated.md -- 直接将RN和Expo添加到现有Gradle和CocoaPods构建流程中（ReactActivity、RCTRootView、Podfile）
  • ./references/comparison.md -- 选择方案的决策标准、权衡因素及场景映射
  • ./references/troubleshooting.md -- 两种方案常见的Metro连接、构建、签名及模块解析问题
更多信息请访问 https://docs.expo.dev/brownfield/overview/

Shared prerequisites

通用前置条件

Both approaches require, in the environment that builds the React Native side:
  • Node.js (LTS) — runs the Expo CLI and JavaScript code.
  • Yarn — manages JavaScript dependencies.
The integrated approach additionally requires CocoaPods on iOS (
sudo gem install cocoapods
). The isolated approach does not require CocoaPods or any RN tooling in the consuming native app.
两种方案都要求在构建React Native端的环境中具备：
  • Node.js (LTS) —— 运行Expo CLI和JavaScript代码。
  • Yarn —— 管理JavaScript依赖。
集成式方案还要求iOS环境中安装CocoaPods（执行
sudo gem install cocoapods
安装）。独立式方案则不要求消费RN的原生应用中安装CocoaPods或任何RN工具链。

Versioning note

版本说明

Expo SDK 55 is the minimum supported version for brownfield integration. Earlier SDKs lack 
expo-brownfield
, the required 
ExpoReactHostFactory
/ 
ExpoReactNativeFactory
entry points, and the current autolinking surface. When creating the Expo project, always pin the SDK explicitly:
sh
npx create-expo-app@latest my-project --template default@sdk-55
Pin the same Expo SDK across both the RN project and any embedded dependencies.
Expo SDK 55是支持brownfield集成的最低版本。 更早的SDK缺少
expo-brownfield
、必需的
ExpoReactHostFactory
/ 
ExpoReactNativeFactory
入口点，以及当前的自动链接机制。创建Expo项目时，请始终明确指定SDK版本：
sh
npx create-expo-app@latest my-project --template default@sdk-55
请确保RN项目和所有嵌入依赖使用相同版本的Expo SDK。