AutoGineer
Generated banner for Expo Brownfield
Generated logo for Expo Brownfield

Expo Brownfield

ExpoOfficialPublished by Expo

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Low risk
Download ZIP

From the author

Integrate Expo and React Native into an existing native iOS or Android app. Use for brownfield, embedding a React Native screen in SwiftUI/UIKit or Kotlin, or AAR/XCFramework packaging. Covers isolated and integrated approaches. For building or distributing a purely native app with EAS, use eas-app-stores.
— the description by Expo

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The expo-brownfield skill provides a structured methodology for adopting React Native incrementally within established native mobile applications. It outlines two primary integration strategies: the isolated approach, which packages React Native code as a prebuilt library (AAR or XCFramework) for teams that want to avoid Node.js dependencies in the host app, and the integrated approach, which incorporates React Native directly into the native build system (Gradle or CocoaPods) for unified development. The skill emphasizes careful host inspection, version compatibility, and feature validation to ensure seamless interoperability between native and React Native components.

What it does

  • Guides the integration of React Native features into existing native iOS and Android codebases.
  • Defines the isolated approach for consuming React Native as a prebuilt library dependency.
  • Defines the integrated approach for embedding React Native directly into native build pipelines.
  • Provides criteria for selecting the appropriate integration strategy based on team structure and build requirements.
  • Outlines prerequisites for environment setup, including Node.js and native build toolchains.
  • Details verification steps to ensure feature functionality and lifecycle management within the host app.

When to use it

  • When adding new features to an existing native app using React Native.
  • When native and React Native teams operate on different release cadences.
  • When you need to minimize the footprint of React Native on the native build pipeline.
  • When a single team owns both native and React Native code and prefers a unified build.

Advantages

  • Supports incremental adoption of React Native in legacy native applications.
  • Offers flexibility to choose between isolated and integrated build workflows.
  • Enables native teams to consume React Native features without requiring Node.js tooling.
  • Maintains compatibility with existing native navigation and UI patterns.
  • Supports standard development workflows like Metro and Fast Refresh.

Usage examples

“How do I add a React Native screen to an existing native Android app without requiring the Android team to install Node.js?”
The agent will guide you through the isolated approach, creating an Expo project and building it as an AAR artifact that the native Android team can consume as a standard dependency.
“We want to integrate Expo into our iOS app and manage everything in one repository. Which approach should I use?”
The agent will recommend the integrated approach, providing steps to add React Native and Expo directly to your CocoaPods setup while preserving your existing native project structure.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/expo/expo-brownfield/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip expo-brownfield.zip -d .agents/skills

Documentation by Expo

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.

Inspect the host first

Identify the existing app entry point, navigation owner, native build system, deployment targets, and any React Native runtime already linked. Record the installed Expo, React Native, and brownfield package versions from the lockfile. Adding EAS Build or Submit to a Swift app alone does not require React Native; route that task to eas-app-stores.

Preserve the host's SwiftUI App / UIKit window and native screens when embedding a feature. Do not run prebuild in a manually maintained native host, including during troubleshooting. An isolated Expo producer may use CNG; keep its generated ios/ and android/ separate from the consuming app.

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.

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.

  • Both approaches support Metro and Fast Refresh in Debug. Choose integrated for shared build ownership, not because isolated lacks live JS iteration.

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, preserving the native app shell

  • ./references/feature-integration.md -- Pass input, return results, dismiss, clean up listeners, and forward lifecycle events; includes a SwiftUI host example

  • ./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.

  • The project's package manager and lockfile — npm, Yarn, pnpm, or Bun. Do not switch package managers just to follow an example.

The iOS build environment needs Xcode and CocoaPods (use the project's Gemfile/Bundler setup when present). The isolated consuming app needs Xcode but no CocoaPods or RN tooling just to consume the artifacts.

Select compatible versions

For an existing Expo/RN project, keep its selected SDK and use npx expo install to align dependencies. Do not upgrade it just to follow this skill. For a new producer, use the current stable SDK compatible with the host's OS support, dependencies, and build toolchain; confirm the release is stable before selecting it.

Before native setup, read ./references/version-compatibility.md for matching native templates, toolchain/OS requirements, and build defaults across SDK versions. A purely native consumer has no Expo SDK version to pin, but must satisfy the artifact's requirements.

Verify the feature in the host

Open the RN screen with input, return a result to native, dismiss, and reopen with fresh input. Check listener cleanup and the host's original navigation. Then build the host in Release with a Release artifact and Metro stopped. Rendering only in Expo Go or the producer's example app does not validate the integration. See ./references/feature-integration.md for the complete acceptance scenario.

Submitting Feedback

If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-brownfield" "<actionable feedback>"

Only submit when you have something specific and actionable to report. Include as much relevant context as possible. If an agent repeatedly fails at an Expo task or the user has to step in, submit a brief report of the task, expected result, and what went wrong using --category evals and the relevant Expo package or command as --subject.

Files

references/comparison.md

Brownfield: Isolated vs. Integrated

Use this reference to choose between the two ways of adding React Native + Expo to an existing native app. If the team and constraints are already known, jump to one of:

Quick decision rules

  • Choose isolated if the native team must consume React Native as a regular library (AAR or XCFramework) without installing Node, Yarn, or RN tooling.

  • Choose isolated if React Native and the native app live in separate repositories, or release on different cadences.

  • Choose isolated if the existing native build is heavily customized (Tuist, Bazel, Buck, custom Gradle plugins) and adding the React Native Gradle plugin or CocoaPods autolinking would be disruptive.

  • Choose integrated if a single team owns the native and React Native code and is willing to maintain the RN build chain inside the native project.

  • Both approaches can use Metro and Fast Refresh in Debug; choose based on artifact/build ownership.

  • Choose integrated if you expect to add many Expo modules and want them autolinked by the standard Expo tooling rather than rebuilt into a fresh artifact each time.

When in doubt — and especially when the question is "can the native team avoid React Native tooling?" — pick isolated.

Comparison

DimensionIsolatedIntegrated
What ships to the native appPrebuilt AAR + XCFrameworkReact Native + Expo sources, autolinked into the existing build
Native team needs Node / Yarn / RN CLINoYes
Build-system footprintArtifact dependency plus its required runtime librariesPervasive — React Native Gradle plugin, Podfile, autolinking, codegen
Iteration speed for RN devsFast in isolation; native rebuild needed to pick up new artifactFast end-to-end; one combined build
Dev-time hot reloadYes (via Metro, when running the consumer app in debug)Yes (native build embeds Metro detection)
Production JS bundle locationEmbedded in the AAR/XCFrameworkEmbedded in the APK/IPA by the RN Gradle plugin / Xcode build phase
Maintenance ownershipRN team owns the artifact pipeline; native team owns the consumer buildOne team owns the unified build
Suitability for incremental adoptionHigh — easy to slot into one screen of an existing appHigh, but with more setup before the first screen renders
Suitability for multi-repo / multi-team setupsHighLow — tends to require a monorepo
Risk of build-system conflicts with existing toolingLowHigher (RN Gradle plugin, codegen, Podfile assumptions)
Re-publish workflow for RN changesnpx expo-brownfield build:* then bump the dependencyRebuild the native app

Common scenarios

"React Native code is in xyz-react and the native apps are in xyz-ios and xyz-android. Each ships independently." → Isolated. Build versioned artifacts (com.xyz:onboarding:1.4.0, Onboarding.xcframework). Native apps pin a version like any other dependency.

"Our app uses a heavily customized Gradle setup with multiple variants and flavors." → Isolated. The RN Gradle plugin is opinionated about variant naming and bundle output paths; integrating cleanly with non-standard variants is non-trivial.

"We don't know yet whether RN will stay — we want to be able to remove it cheaply." → Isolated. Removing the dependency removes the framework; the native build is barely touched.

"Our iOS team uses Tuist and refuses to add Node to the iOS build." → Isolated. Ship an XCFramework. The iOS team adds the generated Swift Package or complete XCFramework set and one call to ReactNativeHostManager.shared.initialize() in AppDelegate. No Node, no CocoaPods changes to Expo.

"We have one repo, one team, and we want to deeply integrate React Native with the onboarding flow to an existing Android app." → Integrated. Keep the host layout or place its Gradle root directly at my-project/android/, add the React Native Gradle plugin to settings.gradle, register MainApplication, and host the flow in a ReactActivity. One build pipeline.

"We want to use CNG on the RN code and not worry about manual RN upgrades." → Isolated. The AAR/XCFramework approach decouples the Expo RN version from the native app's build, so you can upgrade Expo and React Native independently of the native app's release cycle. The integrated approach requires more coordination between the RN version and the native app's build.

What is identical between the approaches

  • The React Native + Expo source code itself — the same Expo project, the same app.json, the same modules — only differs in how it is shipped.

  • The JavaScript module registered with AppRegistry.registerComponent("main", () => App) is the same; the native side passes the same moduleName string in both flows.

What is different at runtime

  • Isolated uses Expo's brownfield runtime wrappers — ReactNativeHostManager, BrownfieldActivity, ReactNativeViewController, ReactNativeView. These are generated by the Expo config plugin and bundled into the artifact.

  • Integrated uses the standard React Native runtime — ReactActivity, ReactActivityDelegate, RCTReactNativeFactory, ExpoReactNativeFactory — exposed by react-native and expo directly.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

What our scanner noticed· Low risk

  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Expo
Publisher
Expo (Official)
Source
expo/skills · plugins/expo/skills/expo-brownfield · commit a9e5bd3
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from plugins/expo/LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Expo.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download expo-brownfield.zip