Back to Details

react-native-brownfield-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrating to React Native

迁移至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.
借助
@callstack/react-native-brownfield
在现有原生应用中渐进式采用React Native的标准化工作流，涵盖从初始设置到分阶段宿主集成的全流程。
  • Expo 路线
  • 原生React Native路线
除非用户明确要求迁移对比，否则每个任务仅使用一条路线。

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.
以下策略适用于Brownfield迁移的规划与执行：
  1. 评估应用状态，选择Expo或原生React Native路线。
  2. 借助
    @callstack/react-native-brownfield
    完成初始设置。
  3. 从React Native源应用打包RN制品（
    XCFramework
    /
    AAR
    ）。
  4. 将一个RN界面集成到宿主应用并验证启动/运行时状态。
  5. 按功能/界面重复集成步骤，实现渐进式部署。

Agent Guardrails (Global)

Agent通用规则

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).
所有参考文档均需遵循以下规则：
  1. 先选择一条路线（Expo或原生），不要混合步骤。
  2. 使用文档中的占位符（
    <framework_target_name>
    、
    <android_module_name>
    、
    <registered_module_name>
    ）并从项目文件中解析实际值。
  3. 在进行宿主集成前，验证每个打包命令。
  4. 对于长平台代码片段和CLI选项细节，优先参考官方文档。
  5. 尽可能让宿主应用与React Native API隔离（外观模式）。

Canonical Docs

权威文档

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.
在选择任何参考文档前，先对项目进行分类：
  1. 若尚未存在React Native应用，使用Expo创建路线：
    • [expo-create-app.md][expo-create-app] -> [expo-quick-start.md][expo-quick-start]
  2. 若已存在React Native应用，检查
    package.json
    和
    app.json
    ：
    • 若包含
      expo
      或要求使用Expo插件工作流，则选择Expo路线。
    • 若包含原生文件夹且使用原生RN CLI工作流、无Expo路线需求，则选择原生RN路线。
  3. 若仍不明确，询问一个澄清问题。
  4. 严格遵循选定的单一路线。

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
在以下场景中参考此工具包：
  • 规划从纯原生应用到React Native或Expo的渐进式迁移
  • 为Expo或原生React Native项目创建Brownfield集成流程
  • 借助
    @callstack/react-native-brownfield
    完成初始设置
  • 从React Native应用生成iOS XCFramework制品
  • 从React Native应用生成并发布Android AAR制品
  • 将生成的制品集成到宿主iOS/Android应用中

Quick Reference

快速参考

FileDescription
[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-integration.md][expo-android-integration]Expo Android packaging, publish, and host integration
[bare-quick-start.md][bare-quick-start]Bare React Native baseline setup
[bare-ios-xcframework-generation.md][bare-ios-xcframework-generation]Bare iOS XCFramework generation
[bare-android-aar-generation.md][bare-android-aar-generation]Bare Android AAR generation and publish
[bare-ios-native-integration.md][bare-ios-native-integration]Bare iOS host integration
[bare-android-native-integration.md][bare-android-native-integration]Bare Android host integration
文件描述
[quick-start.md][quick-start]共享的预检查和强制路线选择前置检查
[expo-create-app.md][expo-create-app]在Expo Brownfield设置前搭建新的Expo应用
[expo-quick-start.md][expo-quick-start]Expo插件设置和打包准备
[expo-ios-integration.md][expo-ios-integration]Expo iOS打包与宿主启动集成
[expo-android-integration.md][expo-android-integration]Expo Android打包、发布与宿主集成
[bare-quick-start.md][bare-quick-start]原生React Native基础设置
[bare-ios-xcframework-generation.md][bare-ios-xcframework-generation]原生iOS XCFramework生成
[bare-android-aar-generation.md][bare-android-aar-generation]原生Android AAR生成与发布
[bare-ios-native-integration.md][bare-ios-native-integration]原生iOS宿主集成
[bare-android-native-integration.md][bare-android-native-integration]原生Android宿主集成

Problem -> Skill Mapping

问题→技能映射

ProblemStart With
Need path decision firstquick-start.md
Need to create a new Expo app for brownfieldexpo-create-app.md
Need Expo brownfield setup and plugin wiringexpo-quick-start.md
Need Expo iOS brownfield integrationexpo-ios-integration.md
Need Expo Android brownfield integrationexpo-android-integration.md
Need bare RN baseline setupbare-quick-start.md
Need bare RN iOS XCFramework generationbare-ios-xcframework-generation.md
Need bare RN Android AAR generation/publishbare-android-aar-generation.md
Need bare RN iOS host integrationbare-ios-native-integration.md
Need bare RN Android host integrationbare-android-native-integration.md
问题起始文档
需要先确定路线quick-start.md
需要为Brownfield创建新的Expo应用expo-create-app.md
需要Expo Brownfield设置和插件配置expo-quick-start.md
需要Expo iOS Brownfield集成expo-ios-integration.md
需要Expo Android Brownfield集成expo-android-integration.md
需要原生RN基础设置bare-quick-start.md
需要原生RN iOS XCFramework生成bare-ios-xcframework-generation.md
需要原生RN Android AAR生成/发布bare-android-aar-generation.md
需要原生RN iOS宿主集成bare-ios-native-integration.md
需要原生RN Android宿主集成bare-android-native-integration.md