---
id: gh-expo-brownfield
name: "expo-brownfield"
url: https://skills.yangsir.net/skill/gh-expo-brownfield
author: expo
domain: mobile
tags: ["react-native", "mobile-development", "ios", "android", "expo"]
install_count: 27200
rating: 4.60 (120 reviews)
github: https://github.com/expo/skills/tree/main/plugins/expo/skills/expo-brownfield
---

# expo-brownfield

> 此技能帮助将 Expo 和 React Native 集成到现有的 iOS 或 Android 原生应用中，支持“棕地”开发模式。它提供隔离式（通过 AAR/XCFramework）和集成式两种方法，使用户能够根据团队结构和技术栈选择最适合的方案，从而平滑地将 React Native 模块嵌入原生项目，提升开发效率。

**Stats**: 27,200 installs · 4.6/5 (120 reviews)

## Before / After 对比

### React Native 棕地集成时间

**Before**:

在没有标准化工具的情况下，将 React Native 手动集成到现有原生应用中，需要耗费大量时间处理环境配置、依赖管理和构建系统兼容性问题，通常需要数天甚至数周的开发工作。

**After**:

借助 Expo Brownfield 提供的隔离式或集成式方案，可以显著简化 React Native 的嵌入过程。特别是隔离式方法，原生团队无需深入了解 Node.js 或 React Native 工具链，大大缩短了集成和配置时间。

| Metric | Before | After | Change |
|---|---|---|---|
| 集成时间 | 40小时 | 8小时 | -80% |

## Readme

# 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:

| Approach       | What ships to the native app                                        | When to choose                                                                   |
| -------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Isolated**   | Prebuilt AAR / XCFramework                                          | Native team doesn't need Node or RN tooling; RN code can live in a separate repo |
| **Integrated** | React Native sources added to the existing Gradle / CocoaPods build | One team owns everything; comfortable with RN tooling; wants a single build      |

For the full decision matrix, see [./references/comparison.md](./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.

## 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/

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

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


---
*Source: https://skills.yangsir.net/skill/gh-expo-brownfield*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-expo-brownfield/markdown*