react-native-brownfield-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrating to React Native

迁移到 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.

仅在已经决定采用 brownfield 迁移之后使用此 skill。当用户仍在 brownfield、greenfield、基于 checkpoint 的路径、推迟或不做迁移之间选择时，请先使用 assess-react-native-migration。

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
```
完成初始设置。
从 RN 源应用打包 RN 制品（
```
XCFramework
```
/
```
AAR
```
）。
将一个 RN surface 集成到宿主应用，并验证启动和运行时状态。
按功能或屏幕重复集成，以逐步推出。

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.
Run
```
npx brownfield <command> --help
```
before relying on any flag table in these references; help output wins.
Write stable project settings once into
```
brownfield.config.*
```
instead of repeating flags — see [cli-and-config.md][cli-and-config].
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.

在所有参考文件中应用以下规则：

先选择一条路径（Expo 或裸 React Native），不得混用步骤。
使用文档中的占位符（
```
<framework_target_name>
```
、
```
<android_module_name>
```
、
```
<registered_module_name>
```
），并根据项目文件确定实际值。
在进入宿主集成前，验证每个打包命令。
依赖这些引用中的任何 flag 表之前，运行
```
npx brownfield <command> --help
```
；以帮助输出为准。
将稳定的项目设置一次性写入
```
brownfield.config.*
```
，避免重复传入 flag——参见 [cli-and-config.md][cli-and-config]。
对于篇幅较长的平台代码片段和 CLI 选项详细信息，优先使用官方文档。
尽可能让宿主应用与直接 React Native API 隔离（facade 方式）。
进行启动和运行时验证时，使用
```
agent-device
```
打开宿主应用、导航至 RN surface、捕获快照或截图，并收集设备证据。如果环境中缺少该工具但验证需要使用，请通过环境批准的可信路径安装，或请用户安装或启用它。

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 应用][expo-create-app] -> [Expo 快速开始][expo-quick-start]
如果已经存在 React Native 应用，检查
```
package.json
```
和
```
app.json
```
：
- 如果存在
```
expo
```
  ，或用户要求使用 Expo 插件工作流，则选择 Expo。
- 如果使用原生目录和直接 RN CLI 工作流，且没有 Expo 路径要求，则选择裸 RN。
如果仍不明确，提出一个澄清问题。
后续严格使用一条路径。

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

在以下情况下参考本 package：

实施已确定采用的从纯原生应用到 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
[cli-and-config.md][cli-and-config]	CLI commands, full flag sets, config file, artifact layout, codegen side effects
[runtime-api.md][runtime-api]	Host <-> RN API surface (JS, Swift, Kotlin) and reference apps
[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]	共享预检和强制路径选择关卡
[cli-and-config.md][cli-and-config]	CLI 命令、完整 flag 集、配置文件、制品目录结构和 codegen 副作用
[runtime-api.md][runtime-api]	宿主 <-> RN API 接口层（JS、Swift、Kotlin）和参考应用
[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

问题 -> Skill 映射

Problem	Start With
Need migration path decision first	assess-react-native-migration
Need Expo vs bare path decision	[quick-start.md][quick-start]
Need a CLI flag, the config file shape, or the artifact paths	[cli-and-config.md][cli-and-config]
Need a host <-> RN API name, signature, or a working example app	[runtime-api.md][runtime-api]
Need shared state between host and RN, or typed RN -> native navigation	`brownie` / `brownfield-navigation` skills
Need to create a new Expo app for brownfield	[expo-create-app.md][expo-create-app]
Need Expo brownfield setup and plugin wiring	[expo-quick-start.md][expo-quick-start]
Need Expo iOS brownfield integration	[expo-ios-integration.md][expo-ios-integration]
Need Expo Android brownfield integration	[expo-android-integration.md][expo-android-integration]
Need bare RN baseline setup	[bare-quick-start.md][bare-quick-start]
Need bare RN iOS XCFramework generation	[bare-ios-xcframework-generation.md][bare-ios-xcframework-generation]
Need bare RN Android AAR generation/publish	[bare-android-aar-generation.md][bare-android-aar-generation]
Need bare RN iOS host integration	[bare-ios-native-integration.md][bare-ios-native-integration]
Need bare RN Android host integration	[bare-android-native-integration.md][bare-android-native-integration]

问题	起点
需要首先决定迁移路径	assess-react-native-migration
需要决定使用 Expo 还是裸 React Native 路径	[quick-start.md][quick-start]
需要了解 CLI flag、配置文件结构或制品路径	[cli-and-config.md][cli-and-config]
需要了解宿主 <-> RN API 名称、签名或可运行的示例应用	[runtime-api.md][runtime-api]
需要宿主与 RN 之间的共享状态，或类型安全的 RN -> 原生导航	`brownie` / `brownfield-navigation` skill
需要为 brownfield 创建新的 Expo 应用	[expo-create-app.md][expo-create-app]
需要 Expo brownfield 设置和插件接线	[expo-quick-start.md][expo-quick-start]
需要 Expo iOS brownfield 集成	[expo-ios-integration.md][expo-ios-integration]
需要 Expo Android brownfield 集成	[expo-android-integration.md][expo-android-integration]
需要裸 RN 基础设置	[bare-quick-start.md][bare-quick-start]
需要生成裸 RN iOS XCFramework	[bare-ios-xcframework-generation.md][bare-ios-xcframework-generation]
需要生成和发布裸 RN Android AAR	[bare-android-aar-generation.md][bare-android-aar-generation]
需要裸 RN iOS 宿主集成	[bare-ios-native-integration.md][bare-ios-native-integration]
需要裸 RN Android 宿主集成	[bare-android-native-integration.md][bare-android-native-integration]