Expo brownfield skill: add React Native to an existing native app

Source: expo/skills · Maintainer: Expo · License: MIT · Checked: 24 October 2026

What is the expo-brownfield skill?

The expo-brownfield skill is Expo's official Agent Skill for adding Expo and React Native to an app that is already native iOS or Android. It helps your coding agent pick between the isolated approach (ship React Native as a prebuilt AAR or XCFramework) and the integrated approach (add React Native to your existing Gradle and CocoaPods builds), then embed and verify a React Native screen without breaking the host app. Install it with npx skills add https://github.com/expo/skills --skill expo-brownfield.

Its description reads: "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." Expo's own brownfield overview points AI agent users to this skill.

As of 24 October 2026, its skills.sh page listed 27.6K installs (snapshot, 24 October 2026). skills.sh first saw it on 19 May 2026.

What does it do?

The skill is model-invoked, so the agent loads it when you ask to bring React Native into a native app. The SKILL.md defines the term first: a brownfield app is "an existing native iOS or Android app that adopts React Native incrementally."

Inspect the host first. Before changing anything, the agent identifies the app's entry point, who owns navigation, the native build system, deployment targets and any React Native runtime already linked, and records the installed Expo, React Native and brownfield package versions from the lockfile. If you only want EAS Build or Submit for a Swift app, the skill says that doesn't need React Native and sends the task to eas-app-stores.

Protect the native app. It tells the agent to keep your SwiftUI App or UIKit window and your native screens, and states: "Do not run prebuild in a manually maintained native host, including during troubleshooting."

Pick an approach.

It adds that both approaches support Metro and Fast Refresh in Debug, so "Choose integrated for shared build ownership, not because isolated lacks live JS iteration."

Match versions. For an existing Expo project, keep its SDK and align packages with npx expo install, and "Do not upgrade it just to follow this skill." For a new producer project, use the current stable SDK that fits the host's OS support and toolchain. A reference file compares SDK 55 and SDK 57 (React Native version, iOS minimum, Node and Xcode versions, and build defaults), and another notes that expo-brownfield was introduced in SDK 55.

Verify inside the host. The test is concrete: open the React Native screen with input, return a result to native, dismiss, reopen with fresh input, check listener cleanup and the host's navigation, then build the host in Release with Metro stopped. "Rendering only in Expo Go or the producer's example app does not validate the integration."

Reference files. Six files load as needed:

• brownfield-isolated.md: building AAR and XCFramework artifacts with npx expo-brownfield build:android and build:ios, and the Kotlin and Swift entry points such as BrownfieldActivity, ReactNativeViewController and the SwiftUI ReactNativeView
• brownfield-integrated.md: adding React Native and Expo directly to existing Gradle and CocoaPods builds
• feature-integration.md: passing input, returning results, dismissing, cleaning up listeners and forwarding lifecycle events, with a SwiftUI host example
• comparison.md: the full decision matrix
• troubleshooting.md: Metro connection, build, signing and module resolution issues
• version-compatibility.md: SDK and toolchain requirements

There is also an agents/openai.yaml for Codex.

How do you install it?

Expo's README recommends the plugin for Claude Code and Codex, and the skills CLI for other agents. The Expo skills docs cover the same routes.

Claude Code plugin (all Expo skills plus the Expo MCP server).

claude plugin install expo@claude-plugins-official

You can also run /plugin install expo@claude-plugins-official inside Claude Code. The plugin comes from Anthropic's official plugin marketplace; see Claude Code plugins.

Codex plugin.

codex plugin add expo@openai-curated

Just this skill, with the skills CLI. The command on skills.sh:

npx skills add https://github.com/expo/skills --skill expo-brownfield

Run it in the repo where the agent will work. The skills CLI puts the skill in .claude/skills/expo-brownfield/ for Claude Code, or ~/.claude/skills/expo-brownfield/ with -g, the standard Claude Code skill locations. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

How do you use it?

Tell the agent about your host app and what the React Native part should do. The skill's first step is reading the host, so give it access to the native project.

Example prompts (suggestions, not quotes from the repo):

• We have a SwiftUI app and want one onboarding flow in React Native. Inspect the project and recommend isolated or integrated.
• Package our Expo feature as an XCFramework and an AAR so the native teams can consume it without Node.
• Embed the React Native checkout screen in our Kotlin app, pass the cart ID in and return the order result.
• The embedded React Native screen can't reach Metro in Debug. Troubleshoot it without running prebuild on the host.
• Check that our brownfield integration works in a Release build with Metro stopped.

Tips and limits

From the SKILL.md, Expo's docs and skills.sh, not from testing:

• Alpha support. Expo's brownfield overview says integrating Expo modules into existing native projects is in alpha and that not all Expo tools and services work there yet. Its table marks Expo Dev Client as unsupported in brownfield, and EAS Build, EAS Submit and EAS Update as supported.
• Toolchain needs. The machine that builds the React Native side needs Node.js (LTS) and the project's package manager; iOS builds need Xcode and CocoaPods. The skill says not to switch package managers just to follow an example. A native app that only consumes the isolated artifacts needs Xcode but no CocoaPods or React Native tooling.
• Versions move fast. The reference file tells the agent to check the installed CLI's --help, generated wrappers and Package.swift, because flags and product names can change within a major release.
• No license line in the frontmatter. Unlike most Expo skills, this SKILL.md has no license field. The MIT LICENSE files at the repo root and in plugins/expo cover it.
• Feedback command. The skill tells the agent it can send feedback to Expo with npx --yes @expo/agent-cli@latest feedback, only when it has something specific to report. Watch for it if you don't want anything sent.
• Audits. On 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub, Socket and Snyk, all three audits dated 22 October 2026.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box; it reads the SKILL.md, the six references/ files and agents/openai.yaml. Paste the repo link instead and Kipt shows a list of Expo skills to pick from, so you can add expo-module in the same pass. Your library stays in a private GitHub repo you own and installs into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Expo.

Similar skills

• Expo module skill: Expo's skill for native modules and views with the Expo Modules API.
• Expo skill (expo-dev-client): development builds for greenfield Expo apps.
• Expo UI skill: native SwiftUI and Jetpack Compose components for the React Native screens you embed.
• SwiftUI expert skill: SwiftUI guidance for the native host on iOS.
• React Native skill: Vercel's React Native and Expo rules for the embedded code.