React Native의 Upgrade Helper

개요

Upgrade Helper는 두 React Native 버전 사이에 변경된 파일을 diff 형태로 보여주는 웹 도구이다. 공식 주소는 다음과 같다.

https://react-native-community.github.io/upgrade-helper/

React Native 프로젝트는 본질적으로 Android 프로젝트 + iOS 프로젝트 + JavaScript(TypeScript) 프로젝트가 합쳐진 구조이다. 따라서 버전을 올릴 때 package.json만 바꾼다고 끝나지 않으며, android/, ios/, Gradle, Podfile, AppDelegate, MainApplication 등 네이티브 영역까지 함께 변경되어야 한다. 이 네이티브 변경 지점을 한눈에 보여주는 것이 Upgrade Helper의 핵심 가치이다.

2. 동작 원리

Upgrade Helper는 rn-diff-purge 프로젝트를 기반으로 동작한다. 원리는 단순하다.

1. CLI로 순수한 RN 앱(RnDiffApp)을 생성한다.
2. 새 RN 버전이 릴리스될 때마다 그 버전의 템플릿으로 앱을 다시 생성한다.
3. 이전 버전과 새 버전의 init 템플릿 차이(diff)를 추출한다.

즉, 사용자가 보는 diff는 "내 코드"가 아니라 RN이 기본 제공하는 템플릿 파일들의 버전 간 차이이다. 그래서 항상 깨끗하고 init 템플릿과 동기화된 상태가 유지된다. 이 차이를 내 프로젝트에 수동으로 반영하는 것이 업그레이드 작업의 본질이다.

3. 사용 방법 (기본 흐름)

1. 도구에 접속한다.
2. 현재 버전(from)과 올릴 버전(to)을 선택한다. 기본값은 최신 메이저 버전이 잡혀 있다.
3. (선택) 앱 이름과 패키지명을 입력하면 diff에 실제 프로젝트명이 반영되어 비교가 수월해진다.
4. Show me how to upgrade 버튼을 누른다.
5. 표시되는 diff를 파일 단위로 내 프로젝트에 반영한다.

가장 먼저 보이는 파일은 package.json이다. 여기에 표시된 의존성 버전부터 맞추는 것이 좋다. 메이저 업데이트의 경우 상단에 useful content 섹션이 나타나며, 해당 버전 업그레이드에 도움이 되는 링크들을 제공한다.

4. 실무에서 유용한 기능

기능	설명
Inline comments	특정 파일에 왜 이 변경이 필요한지 인라인 주석으로 설명해 준다.
Useful content 링크	메이저 업그레이드 시 관련 문서·블로그 링크를 모아서 보여준다.
Done 버튼	파일마다 완료 표시를 할 수 있어 진행 상황을 추적하기 좋다. 파일이 많은 대규모 업그레이드에서 특히 유용하다.
Download 버튼	바이너리 신규 파일(예: gradle wrapper jar)은 diff로 표시할 수 없으므로 직접 다운로드할 수 있게 해준다.
Alt + 클릭	expand/collapse를 alt 키와 함께 누르면 모든 파일을 한 번에 펼치거나 접을 수 있다.

5. CLI upgrade vs Upgrade Helper

업그레이드 방법은 크게 두 가지이다.

1) CLI react-native upgrade

npx @react-native-community/cli@latest upgrade

• 내부적으로 rn-diff-purge를 사용해 어떤 파일을 생성/삭제/수정해야 하는지 계산한다.
• Git 위에서 git apply + 3-way merge로 동작하므로 Git 사용이 필수이다.
• 충돌(conflict)이 나면 ours(내 팀의 코드)와 theirs(RN 팀의 변경)를 직접 머지해야 한다.
• 자동 적용이라 편하지만, 커스텀 네이티브 코드가 많은 대규모 앱에서는 충돌이 복잡하게 얽혀 위험할 수 있다.

2) 수동 + Upgrade Helper

• diff를 보면서 변경 사항을 직접 반영한다.
• 어떤 변경이 왜 일어나는지 이해하면서 진행할 수 있어 통제력이 높다.
• 네이티브 파일을 한땀 한땀 검토하므로 운영 중인 프로덕션 앱에 더 안전하다.

실무 결론

상황	권장 방식
데모/소규모/네이티브 커스텀 거의 없음	CLI upgrade
프로덕션 / 네이티브 코드 많음 / 여러 버전 점프	Upgrade Helper 수동 적용

운영 앱이라면 Upgrade Helper로 직접 반영하는 쪽이 더 안전하고 통제 가능한 선택이다.

6. 실무 업그레이드 워크플로우

아래 순서대로 진행하면 사고를 크게 줄일 수 있다.

1. 브랜치 분리 — chore/rn-upgrade-x.y.z 같은 별도 브랜치를 판다. 롤백 안전장치를 먼저 확보하는 것이다.
2. 환경(Node/JDK/Xcode/Android Studio) 점검 — 대부분의 업그레이드 실패는 환경 요구사항을 건너뛰어 발생한다.
3. 버전 점프 폭 결정 — 한 번에 너무 멀리 점프하지 않는다. 메이저 마이너 여러 개를 건너뛰면 충돌 해석이 기하급수적으로 어려워진다.
4. Upgrade Helper에서 diff 확인 — package.json → JS 설정 파일 → Android → iOS 순으로 반영한다.
5. 네이티브 파일 우선 검토 — Gradle, AppDelegate, MainApplication, Podfile, build.gradle 등 충돌이 잦은 파일을 신경 써서 본다.
6. 서드파티 라이브러리 호환성 감사 — 모든 네이티브 의존 패키지가 대상 RN 버전(특히 New Architecture)을 지원하는지 확인한다.
7. 단계별 커밋 — 영역별(JS / Android / iOS)로 나눠 커밋해 문제 추적과 롤백을 쉽게 만든다.
8. 클린 빌드 + 실기기 테스트 — node_modules, Pods, Gradle 캐시, Metro 캐시를 모두 비우고 빌드한다.

메이저 마이너를 올릴 때는 올리기 전후로 네이티브 템플릿 diff를 Upgrade Helper에서 항상 비교하는 습관을 들이는 것이 좋다.

7. 반드시 알아야 할 핵심 주의사항 (2026년 기준)

New Architecture는 더 이상 선택이 아니다

New Architecture(JSI, TurboModules, Fabric, Codegen)는 이제 사실상 필수이다.

환경 요구사항을 먼저 맞춘다

예를 들어 0.85는 EOL Node 버전(v21, v23)과 20.19.4 미만 버전을 지원하지 않는다. 업그레이드 전에 Node/JDK/Xcode/Android SDK가 대상 버전 요건을 충족하는지 확인하는 것이 첫 단추이다.

Hermes 전제

New Architecture는 JSI 위에 구축되어 있고 Hermes에 의존한다. JavaScriptCore에서는 동작하지 않으므로 Hermes 사용을 전제로 둔다.

자주 깨지는 지점들

• SafeAreaView는 deprecated 경로이다. react-native-safe-area-context로 대체하고, 중첩 네비게이터에서 잘 동작하는지 검증한다.
• Android 16(API 36) edge-to-edge 대응 시 라이트/다크 시스템 바, inset, 모달 오버레이를 함께 테스트한다.
• Android 뒤로가기(back) 커스텀 처리는 물리 버튼과 제스처 양쪽 모두 테스트한다.
• StyleSheet.absoluteFillObject 등 장기간 deprecated 였던 API가 메이저 버전에서 완전히 제거될 수 있으므로 릴리스 노트를 확인한다.

8. 서드파티 라이브러리 호환성 감사 (Upgrade Helper 범위 밖)

Upgrade Helper는 서드파티 라이브러리를 다루지 않으므로, 이 영역은 별도 트랙으로 직접 챙겨야 한다. 실무 절차는 다음과 같다.

1) React Native Directory에서 먼저 확인

reactnative.directory는 RN 팀이 관리하는 공식 패키지 데이터베이스이며, 각 라이브러리의 New Architecture 호환 여부가 표시된다. 마이그레이션 전에 여기서 주요 의존성을 훑는 것이 출발점이다.

https://reactnative.directory/

2) package.json 전체를 일괄 검사

Directory 사이트는 패키지를 하나씩만 조회할 수 있어, 실무에서는 일괄 검사 도구가 효율적이다.

도구	형태	설명
react-native-package-checker	웹	package.json 의존성 전체를 한 번에 검사해 New Architecture 호환성을 시각화하고 리포트로 내보낼 수 있다.
react-native-check-new-archi	CLI	프로젝트 루트에서 실행하면 Directory API로 각 라이브러리를 조회하고, 목록에 없으면 GitHub 저장소를 분석해 순수 JS 구현인지(=호환 가능성)까지 판단해 준다.
npm outdated	CLI(기본)	어떤 의존성에 더 최신(호환) 버전이 나와 있는지 확인하는 가장 기본적인 방법이다.

3) 호환성 플래그의 함정에 주의

Directory의 newArch 플래그는 버전 단위가 아니라 라이브러리 단위의 binary 값이다. 즉, 라이브러리의 최신 버전은 New Architecture를 지원하지만 내가 쓰는 구버전은 지원하지 않는 경우에도, Directory가 그 라이브러리를 호환으로 표시하기 때문에 도구가 문제를 놓칠 수 있다. 따라서 "이 라이브러리가 지원함"이 아니라 "내가 쓰는 버전이 지원함"을 changelog/릴리스 노트로 한 번 더 확인하는 것이 안전하다.

(4) 감사 우선순위를 네이티브 의존 패키지에 둔다

JS나 RN 코어 API만 사용하는 라이브러리는 (비공개·문서화되지 않은 API를 쓰지 않는 한) 대체로 변경 없이 동작한다. 반면 네이티브 코드를 직접 포함하거나 의존하는 라이브러리가 업데이트를 요구할 가능성이 높다. 따라서 다음과 같은 패키지에 감사 우선순위를 둔다.

• 애니메이션·제스처 — react-native-reanimated, react-native-gesture-handler
• 네비게이션 스택 기반 — react-native-screens
• 푸시·결제·지도·카메라 등 네이티브 SDK 래퍼 — @notifee/react-native, 결제/지도/카메라 모듈류
• 직접 작성한 네이티브 모듈 — 구 RCTBridgeModule API 기반이라면 TurboModule(Codegen)로 재작성이 필요하다.

8. 자주 겪는 트러블슈팅

• Git 없이 CLI upgrade 사용 — CLI는 git apply에 의존하므로 Git이 없으면 동작하지 않는다. 공식 Troubleshooting에 우회법이 있지만, 가능하면 Git 환경에서 작업한다.
• 머지 충돌 폭증 — 한 번에 너무 많은 버전을 점프하면 발생한다. 중간 버전을 거쳐 단계적으로 올리는 편이 낫다.
• 빌드는 되는데 런타임 크래시 — 서드파티 네이티브 라이브러리의 New Architecture 미지원이 원인인 경우가 많다. 업그레이드 전에 의존성 호환성을 먼저 감사한다.
• iOS Pod 관련 오류 — Podfile.lock 삭제, pod deintegrate 후 재설치, 그리고 diff에 반영된 Podfile 변경이 누락되지 않았는지 확인한다.