React Native Brownfield Migration
Incrementally embed React Native or Expo screens into existing native iOS and Android apps using Callstack brownfield packaging instead of a risky full rewrite.
Overview
React Native Brownfield Migration is an agent skill most often used in Build (also Validate scope planning) that guides incremental React Native or Expo adoption in existing iOS and Android apps via `@callstack/react-nat
Install
npx skills add https://github.com/callstackincubator/agent-skills --skill react-native-brownfield-migrationWhat is this skill?
- Five-step migration strategy from assessment through phased host integration
- Parallel Expo track and bare React Native track with explicit guardrail to not mix steps
- Initial setup via `@callstack/react-native-brownfield` before artifact packaging
- XCFramework and AAR packaging workflow from the RN source app into host apps
- Placeholder-driven integration docs for framework targets and Android module names
- 5-step migration strategy from assessment through repeated feature integration
- 2 explicit tracks: Expo and bare React Native (one per task)
Adoption & trust: 2.5k installs on skills.sh; 1.4k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a production native app and cannot afford a full React Native rewrite but need to ship new UI faster than pure Swift or Kotlin allows.
Who is it for?
Teams with shipping native apps who want a documented, screen-by-screen RN migration using Callstack brownfield tooling.
Skip if: Greenfield apps with no native host, or teams that need both Expo and bare migration steps interleaved in one task without explicit comparison intent.
When should I use this skill?
Planning migration steps, packaging XCFramework/AAR artifacts, or integrating React Native into host native apps with `@callstack/react-native-brownfield`.
What do I get? / Deliverables
You follow one Expo or bare path through brownfield setup, produce XCFramework/AAR packages, and validate an integrated RN screen ready for repeated feature rollout.
- Packaged XCFramework and/or AAR artifacts
- Host app integration with at least one validated RN surface
- Phased rollout plan for additional screens
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build is the canonical shelf because execution centers on packaging XCFramework/AAR artifacts and integrating RN surfaces into live host apps. Frontend mobile subphase matches brownfield UI rollout—one screen or feature at a time in a native shell—not greenfield backend or infra work.
Where it fits
Compare Expo versus bare brownfield paths and define which native screens migrate first.
Run `@callstack/react-native-brownfield` setup and package the first RN feature as XCFramework/AAR.
Register the brownfield module in the host app using documented placeholder names for targets and Android modules.
Smoke-test cold start and navigation handoff between native shell and the embedded RN surface before store submission.
How it compares
Use this brownfield integration playbook instead of starting a parallel greenfield React Native app when your users and auth already live in native hosts.
Common Questions / FAQ
Who is react-native-brownfield-migration for?
Indie and small-team mobile developers maintaining legacy iOS or Android codebases who want React Native screens without stopping feature shipping for a monolithic rewrite.
When should I use react-native-brownfield-migration?
Use it in Validate when scoping Expo versus bare and migration phases; in Build when packaging frameworks and wiring the first RN surface; and in Ship when validating startup and runtime in the host app before wider rollout.
Is react-native-brownfield-migration safe to install?
It is procedural documentation for native build changes—review the Security Audits panel on this Prism page and run integration on branches with full Xcode/Android Studio backups before touching production release pipelines.
SKILL.md
READMESKILL.md - React Native Brownfield Migration
# Migrating to React Native ## Overview Prescriptive workflow for incremental adoption of React Native in existing native apps using `@callstack/react-native-brownfield`, from initial setup through phased host integration. - Expo track - Bare React Native track Use one track per task unless the user explicitly asks for migration or comparison. ## Migration Strategy Use this strategy for brownfield migration planning and execution: 1. Assess app state and select Expo or bare path. 2. Perform initial setup with `@callstack/react-native-brownfield`. 3. Package RN artifacts (`XCFramework`/`AAR`) from the RN source app. 4. Integrate one RN surface into the host app and validate startup/runtime. 5. Repeat integration by feature/screen for incremental rollout. ## Agent Guardrails (Global) Apply these rules across all reference files: 1. Select one path first (Expo or bare) and do not mix steps. 2. Use placeholders from the docs (`<framework_target_name>`, `<android_module_name>`, `<registered_module_name>`) and resolve from project files. 3. Validate each packaging command before moving to host integration. 4. Prefer official docs for long platform snippets and CLI option details. 5. Keep host apps isolated from direct React Native APIs when possible (facade approach). ## Canonical Docs - [Quick Start](https://oss.callstack.com/react-native-brownfield/docs/getting-started/quick-start.md) - [Expo Integration](https://oss.callstack.com/react-native-brownfield/docs/getting-started/expo.md) - [iOS Integration](https://oss.callstack.com/react-native-brownfield/docs/getting-started/ios.md) - [Android Integration](https://oss.callstack.com/react-native-brownfield/docs/getting-started/android.md) - [Brownfield CLI](https://oss.callstack.com/react-native-brownfield/docs/cli/brownfield.md) - [Guidelines](https://oss.callstack.com/react-native-brownfield/docs/guides/guidelines.md) - [Troubleshooting](https://oss.callstack.com/react-native-brownfield/docs/guides/troubleshooting.md) ## Path Selection Gate (Must Run First) Before selecting any reference file, classify the project: 1. If no React Native app exists yet, use Expo creation path: - [expo-create-app.md][expo-create-app] -> [expo-quick-start.md][expo-quick-start] 2. If React Native app exists, inspect `package.json` and `app.json`: - Expo if `expo` is present or Expo plugin workflow is requested. - Bare RN if native folders and direct RN CLI workflow are used without Expo path requirements. 3. If still unclear, ask one disambiguation question. 4. Continue with exactly one path. ## When to Apply Reference this package when: - Planning incremental migration from native-only apps to React Native or Expo - Creating brownfield integration flows for Expo or bare React Native projects - Performing initial setup with `@callstack/react-native-brownfield` - Generating iOS XCFramework artifacts from a React Native app - Generating and publishing Android AAR artifacts from a React Native app - Integrating generated artifacts into host iOS/Android apps ## Quick Reference | File | Description | |------|-------------| | [quick-start.md][quick-start] | Shared preflight and mandatory path-selection gate | | [expo-create-app.md][expo-create-app] | Scaffold a new Expo app before Expo brownfield setup | | [expo-quick-start.md][expo-quick-start] | Expo plugin setup and packaging readiness | | [expo-ios-integration.md][expo-ios-integration] | Expo iOS packaging and host startup integration | | [expo-android-integra