React Native로 마이그레이션하기
이 스킬은 브라운필드 마이그레이션을 도입하기로 결정한 후에만 사용하십시오. 사용자가 여전히 브라운필드, 그린필드, 체크포인트 기반 경로, 연기 또는 마이그레이션 안 함 중에서 선택 중인 경우, 먼저 assess-react-native-migration을 사용하십시오.
개요
@callstack/react-native-brownfield를 사용하여 기존 네이티브 앱에 React Native를 점진적으로 도입하기 위한 규범적 워크플로우입니다. 초기 설정부터 단계별 호스트 통합까지를 다룹니다.
- Expo 트랙
- Bare React Native 트랙
사용자가 명시적으로 마이그레이션이나 비교를 요청하지 않는 한, 작업당 하나의 트랙을 사용하십시오.
마이그레이션 전략
브라운필드 마이그레이션 계획 및 실행을 위해 이 전략을 사용하십시오:
- 앱 상태를 평가하고 Expo 또는 Bare 경로를 선택합니다.
@callstack/react-native-brownfield로 초기 설정을 수행합니다.- RN 소스 앱에서 RN 아티팩트(
XCFramework/AAR)를 패키징합니다. - 하나의 RN 화면을 호스트 앱에 통합하고 시작/런타임을 검증합니다.
- 기능/화면별로 통합을 반복하여 점진적으로 롤아웃합니다.
에이전트 가드레일 (전역)
다음 규칙을 모든 참조 파일에 적용하십시오:
- 먼저 하나의 경로(Expo 또는 Bare)를 선택하고 단계를 혼합하지 마십시오.
- 문서의 플레이스홀더(
<framework_target_name>,<android_module_name>,<registered_module_name>)를 사용하고 프로젝트 파일에서 해결하십시오. - 호스트 통합으로 넘어가기 전에 각 패키징 명령을 검증하십시오.
- 이 참조의 플래그 테이블에 의존하기 전에
npx brownfield <command> --help를 실행하십시오. 도움말 출력이 우선합니다. - 플래그를 반복하는 대신 안정적인 프로젝트 설정을
brownfield.config.*에 한 번 작성하십시오. cli-and-config.md를 참조하십시오. - 긴 플랫폼 코드 조각 및 CLI 옵션 세부 정보는 공식 문서를 선호하십시오.
- 가능하면 호스트 앱을 직접적인 React Native API로부터 격리하십시오(퍼사드 접근법).
- 시작/런타임 검증을 위해
agent-device를 사용하여 호스트 앱을 열고, RN 화면으로 이동하며, 스냅샷/스크린샷을 캡처하고, 장치 증거를 수집하십시오.agent-device가 없고 검증에 필요하면, 환경의 승인된/신뢰된 경로를 통해 설치하거나 사용자에게 설치 또는 활성화를 요청하십시오.
정식 문서
경로 선택 게이트 (먼저 실행 필수)
참조 파일을 선택하기 전에 프로젝트를 분류하십시오:
- 아직 React Native 앱이 없는 경우, Expo 생성 경로를 사용하십시오:
- React Native 앱이 존재하는 경우,
package.json과app.json을 검사하십시오:expo가 존재하거나 Expo 플러그인 워크플로우가 요청된 경우 Expo.- 네이티브 폴더와 직접 RN CLI 워크플로우가 사용되고 Expo 경로 요구사항이 없는 경우 Bare RN.
- 여전히 명확하지 않으면, 하나의 명확화 질문을 하십시오.
- 정확히 하나의 경로로 계속 진행하십시오.
적용 시점
다음 상황에서 이 패키지를 참조하십시오:
- 네이티브 전용 앱에서 React Native 또는 Expo로의 승인된 점진적 마이그레이션을 구현할 때
- Expo 또는 Bare React Native 프로젝트를 위한 브라운필드 통합 흐름을 생성할 때
@callstack/react-native-brownfield로 초기 설정을 수행할 때- React Native 앱에서 iOS XCFramework 아티팩트를 생성할 때
- React Native 앱에서 Android AAR 아티팩트를 생성하고 게시할 때
- 생성된 아티팩트를 호스트 iOS/Android 앱에 통합할 때
빠른 참조
| 파일 | 설명 |
|---|---|
| quick-start.md | 공통 사전 점검 및 필수 경로 선택 게이트 |
| cli-and-config.md | CLI 명령어, 전체 플래그 세트, 설정 파일, 아티팩트 레이아웃, 코드 생성 부수 효과 |
| runtime-api.md | 호스트 <-> RN API 표면(JS, Swift, Kotlin) 및 참조 앱 |
| expo-create-app.md | Expo 브라운필드 설정 전에 새 Expo 앱 스캐폴딩 |
| expo-quick-start.md | Expo 플러그인 설정 및 패키징 준비 |
| expo-ios-integration.md | Expo iOS 패키징 및 호스트 시작 통합 |
| expo-android-integration.md | Expo Android 패키징, 게시 및 호스트 통합 |
| bare-quick-start.md | Bare React Native 기준 설정 |
| bare-ios-xcframework-generation.md | Bare iOS XCFramework 생성 |
| bare-android-aar-generation.md | Bare Android AAR 생성 및 게시 |
| bare-ios-native-integration.md | Bare iOS 호스트 통합 |
| bare-android-native-integration.md | Bare Android 호스트 통합 |
문제 -> 스킬 매핑
| 문제 | 시작 지점 |
|---|---|
| 먼저 마이그레이션 경로 결정이 필요함 | assess-react-native-migration |
| Expo 대 Bare 경로 결정이 필요함 | quick-start.md |
| CLI 플래그, 설정 파일 형태, 또는 아티팩트 경로가 필요함 | cli-and-config.md |
| 호스트 <-> RN API 이름, 시그니처, 또는 작동하는 예제 앱이 필요함 | runtime-api.md |
| 호스트와 RN 간 공유 상태, 또는 타입화된 RN -> 네이티브 내비게이션이 필요함 | brownie / brownfield-navigation 스킬 |
| 브라운필드를 위한 새 Expo 앱을 생성해야 함 | expo-create-app.md |
| Expo 브라운필드 설정 및 플러그인 연결이 필요함 | expo-quick-start.md |
| Expo iOS 브라운필드 통합이 필요함 | expo-ios-integration.md |
| Expo Android 브라운필드 통합이 필요함 | expo-android-integration.md |
| Bare RN 기준 설정이 필요함 | bare-quick-start.md |
| Bare RN iOS XCFramework 생성이 필요함 | bare-ios-xcframework-generation.md |
| Bare RN Android AAR 생성/게시가 필요함 | bare-android-aar-generation.md |
| Bare RN iOS 호스트 통합이 필요함 | bare-ios-native-integration.md |
| Bare RN Android 호스트 통합이 필요함 | bare-android-native-integration.md |
관련 스킬
- 마이그레이션 경로를 선택하기 전에 Assess React Native migration를 먼저 사용하십시오.
brownie(공유 호스트 <-> RN 상태) 및brownfield-navigation(타입화된 RN -> 네이티브 내비게이션)은 다른 저장소에서 제공됩니다. 이름으로 호출하고, 설치되지 않은 경우 정식 문서로 대체하십시오.