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:

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.

以下策略适用于Brownfield迁移的规划与执行：

评估应用状态，选择Expo或原生React Native路线。
借助
```
@callstack/react-native-brownfield
```
完成初始设置。
从React Native源应用打包RN制品（
```
XCFramework
```
/
```
AAR
```
）。
将一个RN界面集成到宿主应用并验证启动/运行时状态。
按功能/界面重复集成步骤，实现渐进式部署。

Agent Guardrails (Global)

Agent通用规则

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).

所有参考文档均需遵循以下规则：

先选择一条路线（Expo或原生），不要混合步骤。
使用文档中的占位符（
```
<framework_target_name>
```
、
```
<android_module_name>
```
、
```
<registered_module_name>
```
）并从项目文件中解析实际值。
在进行宿主集成前，验证每个打包命令。
对于长平台代码片段和CLI选项细节，优先参考官方文档。
尽可能让宿主应用与React Native API隔离（外观模式）。

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:
- [expo-create-app.md][expo-create-app] -> [expo-quick-start.md][expo-quick-start]
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.

在选择任何参考文档前，先对项目进行分类：

若尚未存在React Native应用，使用Expo创建路线：
- [expo-create-app.md][expo-create-app] -> [expo-quick-start.md][expo-quick-start]
若已存在React Native应用，检查
```
package.json
```
和
```
app.json
```
：
- 若包含
```
expo
```
  或要求使用Expo插件工作流，则选择Expo路线。
- 若包含原生文件夹且使用原生RN CLI工作流、无Expo路线需求，则选择原生RN路线。
若仍不明确，询问一个澄清问题。
严格遵循选定的单一路线。

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

快速参考

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-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

问题→技能映射

Problem	Start With
Need path decision first	quick-start.md
Need to create a new Expo app for brownfield	expo-create-app.md
Need Expo brownfield setup and plugin wiring	expo-quick-start.md
Need Expo iOS brownfield integration	expo-ios-integration.md
Need Expo Android brownfield integration	expo-android-integration.md
Need bare RN baseline setup	bare-quick-start.md
Need bare RN iOS XCFramework generation	bare-ios-xcframework-generation.md
Need bare RN Android AAR generation/publish	bare-android-aar-generation.md
Need bare RN iOS host integration	bare-ios-native-integration.md
Need bare RN Android host integration	bare-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