expo-brownfield

bởi expo

Khung (OSS). Tích hợp Expo và React Native vào ứng dụng iOS hoặc Android gốc hiện có. Sử dụng khi người dùng đề cập đến brownfield, nhúng React Native vào…

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

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

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.

Thêm skills từ expo

add-app-clip
expo
Thêm mục tiêu App Clip iOS vào ứng dụng Expo. Sử dụng khi người dùng đề cập đến App Clip, AASA, apple-app-site-association, appclips, smart app banner, hoặc muốn phát hành…
android-e2e-testing
expo
Kiểm tra các tính năng Expo Router trên trình giả lập Android bằng ADB. Sử dụng sau khi triển khai các tính năng Android gốc hoặc khi xác minh hành vi giao diện người dùng trên Android.
android-jetpack-compose
expo
Sử dụng khi xây dựng giao diện Android với Jetpack Compose, quản lý trạng thái bằng remember/mutableStateOf, hoặc triển khai các mẫu giao diện khai báo.
api-routes
expo
Hướng dẫn tạo API routes trong Expo Router với EAS Hosting
building-native-ui
expo
Hướng dẫn đầy đủ để xây dựng ứng dụng Expo gốc với routing, tạo kiểu, component và quy ước nền tảng. Bao gồm các kiến thức cơ bản về Expo Router, tab gốc, stack navigation, modal và form sheet với quy ước cấu trúc route chi tiết. Bao gồm các quy tắc tạo kiểu tuân theo Nguyên tắc Giao diện Người dùng Apple: bố cục flexbox, xử lý vùng an toàn, hoạt ảnh, đổ bóng qua CSS boxShadow và các mẫu thiết kế đáp ứng. Ghi lại các tùy chọn thư viện (expo-image cho SF Symbols, expo-audio, expo-video,...)
building-ui
expo
Hướng dẫn hoàn chỉnh để xây dựng ứng dụng đẹp với Expo Router. Bao gồm các kiến thức cơ bản, tạo kiểu, thành phần, điều hướng, hoạt ảnh, mẫu thiết kế và tab gốc.
cicd-workflows
expo
Giúp hiểu và viết các tệp YAML quy trình EAS cho các dự án Expo. Sử dụng kỹ năng này khi người dùng hỏi về CI/CD hoặc quy trình trong bối cảnh Expo hoặc EAS,…
data-fetching
expo
Sử dụng khi triển khai hoặc gỡ lỗi BẤT KỲ yêu cầu mạng, lệnh gọi API hoặc việc tải dữ liệu nào. Bao gồm fetch API, axios, React Query, SWR, xử lý lỗi, bộ nhớ đệm…