72 lines
4.5 KiB
Markdown
72 lines
4.5 KiB
Markdown
---
|
|
name: expo-brownfield
|
|
description: Integrate Expo and React Native into an existing native iOS or Android app. Use when the user mentions brownfield, embedding React Native in a native app, AAR/XCFramework, or adding Expo to an existing Kotlin/Swift project. Covers both the isolated approach and the integrated approach.
|
|
risk: unknown
|
|
source: https://github.com/expo/skills/tree/main/plugins/expo/skills/expo-brownfield
|
|
source_repo: expo/skills
|
|
source_type: official
|
|
date_added: 2026-07-01
|
|
license: MIT
|
|
license_source: https://github.com/expo/skills/blob/main/LICENSE
|
|
---
|
|
|
|
# Expo Brownfield
|
|
## When to Use
|
|
|
|
Use this skill when you need integrate Expo and React Native into an existing native iOS or Android app. Use when the user mentions brownfield, embedding React Native in a native app, AAR/XCFramework, or adding Expo to an existing Kotlin/Swift project. Covers both the isolated approach and the integrated approach.
|
|
|
|
|
|
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.
|
|
|
|
## Limitations
|
|
|
|
- Use this skill only when the task clearly matches its upstream product or API scope.
|
|
- Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
|
|
- Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
|