| name | react-native-brownfield-migration |
| description | Implements an accepted incremental brownfield migration from native iOS or Android to React Native or Expo using @callstack/react-native-brownfield. Use after the brownfield path has been selected, when setting up the integration, packaging XCFramework or AAR artifacts, or adding React Native surfaces to native hosts. |
| license | MIT |
Migrating to React Native
Use this skill only after the decision to adopt brownfield migration has been made. When the user is still choosing between brownfield, greenfield, a checkpoint-based path, defer, or no migration, use assess-react-native-migration first.
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:
- Assess app state and select Expo or bare path.
- Perform initial setup with
@callstack/react-native-brownfield.
- Package RN artifacts (
XCFramework/AAR) from the RN source app.
- Integrate one RN surface into the host app and validate startup/runtime.
- Repeat integration by feature/screen for incremental rollout.
Agent Guardrails (Global)
Apply these rules across all reference files:
- Select one path first (Expo or bare) and do not mix steps.
- Use placeholders from the docs (
<framework_target_name>, <android_module_name>, <registered_module_name>) and resolve from project files.
- Validate each packaging command before moving to host integration.
- Prefer official docs for long platform snippets and CLI option details.
- Keep host apps isolated from direct React Native APIs when possible (facade approach).
- For startup/runtime verification, use
agent-device to open the host app, navigate to the RN surface, capture snapshots/screenshots, and collect device evidence. If it is missing and verification needs it, install it through the environment's approved/trusted path or ask the user to install or enable it.
Canonical Docs
Path Selection Gate (Must Run First)
Before selecting any reference file, classify the project:
- If no React Native app exists yet, use Expo creation path:
- 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.
- If still unclear, ask one disambiguation question.
- Continue with exactly one path.
When to Apply
Reference this package when:
- Implementing an accepted 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
Problem -> Skill Mapping
Related Skills
