Index of every page on this site: llms.txt
All skills
expo avatar

/expo-brownfield

@88d9bd7 official
by expoexpo/skills4.2k stars
277
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/expo/skills/expo-brownfield

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈81 tokens for metadata: the name and description. ≈1.4k when used: this file. ≈19k more on demand in 7 files.

Description uses 4.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈325 characters, or 4.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

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.

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

You can voluntarily report errors, misleading or outdated information in this skill, so Expo can improve it:

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

Use --category agent-cli for a problem with the agent CLI, and --category evals when an agent repeatedly fails at an Expo task. Run feedback --help for subjects and the data that the command sends. Each report goes to Expo with project and environment details. Show the user the message, and send it only if the user agrees. If you cannot ask the user, do not send it. Do not include secrets or personal data.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning5d3 checks · Risk SAFE
  • Gen Agent Trust Hub6d

    The skill provides legitimate and secure instructions for integrating Expo and React Native into native iOS and Android applications, utilizing official vendor tools and following industry-standard configuration patterns.

  • Socket5d

    No alerts

  • Snyk6d

    Risk: MEDIUM · 1 issue

Signed by skilld at 88d9bd7. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week
  • expo
  • react-native
  • brownfield
  • ios
  • android
  • native-integration
  • aar
  • xcframework
  • kotlin
  • swift

README badge

README badge for expo/skills/expo-brownfield

Integrates React Native and Expo into an existing native iOS or Android app using either isolated (AAR/XCFramework) or integrated (Gradle/CocoaPods) approaches. Choose isolated if the native team needs no Node tooling or RN lives in a separate repo; choose integrated if one team owns both codebases and wants hot reload in the native build.

Generated from the current SKILL.md.

What is the difference between isolated and integrated approaches?
Isolated builds React Native as a prebuilt AAR or XCFramework that the native team consumes without needing Node or RN tooling installed. Integrated adds React Native sources directly to the existing Gradle and CocoaPods build, requiring a single team to manage both native and RN code together.
Which approach should I use if my native and React Native teams are separate?
Choose isolated. It lets the iOS/Android team consume React Native as a regular library dependency without installing Node, Yarn, or the React Native build toolchain, and allows the codebases to live in separate repositories and release independently.
What is the minimum Expo SDK version for brownfield?
Expo SDK 55 or later. Earlier SDKs lack the required ExpoReactHostFactory and ExpoReactNativeFactory entry points and the current autolinking surface. Always pin the SDK explicitly when creating the Expo project.
Do both approaches require Node.js and Yarn?
Yes, Node.js (LTS) and Yarn are required in the environment that builds the React Native side. The integrated approach additionally requires CocoaPods on iOS; the isolated approach does not.

Generated from the current SKILL.md. These answers refresh after source changes.