| name | react-native-brownfield-migration |
| description | Provides an incremental adoption strategy to migrate native iOS or Android apps to React Native or Expo using @callstack/react-native-brownfield for initial setup. Use when planning migration steps, packaging XCFramework/AAR artifacts, and integrating them into host apps. |
| license | MIT |
| metadata | {"author":"Callstack","tags":"react-native, brownfield, expo, bare, ios, android, xcframework, aar, native-integration","vendored_from":"github:callstackincubator/agent-skills@0ba043ab"} |
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.
In the ATLAS app-dev system: this is the entry point for embedding RN/Expo into an existing native iOS/Android app (XCFramework/AAR packaging + host integration) — distinct from greenfield mobile work (new-mobile-app, tactile, building-native-ui). Covers both the bare-RN and Expo tracks. Native-integration scope, so it triggers on brownfield projects rather than the user's default Expo/EAS greenfield path.
- 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:
- 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
Problem -> Skill Mapping
