React Native 업그레이드: package.json 다음에 무엇을 맞추는가

30초 요약

React Native 업그레이드는 react-native 패키지 하나를 바꾸는 일이 아니다. 이 글의 Community CLI 방식은 명령줄 도구로 앱을 만들고 Android·iOS 프로젝트 폴더를 개발자가 직접 소유한다. JavaScript 프로젝트까지 세 실행 입력을 같은 목표에 맞춰야 한다.

현재 기준선 고정
→ 목표 지원 버전과 호환 조합 선택
→ release note + Upgrade Helper로 해야 할 일 추출
→ package·lockfile + 생성 프로젝트 차이 적용
→ JavaScript 도구 → Android → iOS 순서로 실패 범위 축소
→ 양쪽 개발용(Debug) 실행 → 핵심 네이티브 흐름 → 배포용(Release) 빌드
→ 필요한 실제 장치 능력만 실기기에서 확인

반복해서 기억할 문장은 이것이다.

패키지를 설치하지 말고, 세 프로젝트를 같은 목표 버전으로 정렬한다.

이 글은 Expo가 관리하는 프로젝트가 아니라 Android와 iOS 폴더를 직접 소유하는 Community CLI 앱을 다룬다. Expo 프로젝트는 공식 SDK 업그레이드 절차와 그 SDK가 정한 React Native 조합을 따라야 하며, 아래의 직접 소유 프로젝트 diff를 그대로 복사하면 안 된다.

이 글을 관통하는 상황: 0.84 앱의 package.json만 0.85로 바꾼다

Community template은 Community CLI가 특정 React Native 버전의 새 앱을 만들 때 사용하는 기준 프로젝트 파일 묶음이다. 이 template으로 만든 RnDiffApp이 React Native 0.84.0에서 테스트·Android·iOS 빌드와 시작까지 통과한다고 하자. 목표는 0.85.0이다. 이 역사적 전환을 택한 이유는 현재 최신 숫자를 외우기 위해서가 아니라 한 번의 minor 이동에서 세 프로젝트가 어떻게 함께 달라지는지 관찰하기 위해서다.

기존 앱이 없다면 저장소 밖의 연습용 디렉터리에서 다음과 같이 0.84.0 기준선을 만든다. CLI는 React Native 프로젝트를 만들고 실행 명령을 제공하는 명령줄 도구다.

npx @react-native-community/[email protected] init RnDiffApp \
  --version 0.84.0 \
  --install-pods true
cd RnDiffApp

이 연습의 Node.js는 정확한 비교를 위해 22.11.0으로 고정한다. 0.85 공식 안내의 지원 집합은 Node 20의 20.19.4 이상, Node 22, Node 24 이상이며 지원이 종료된 Node 21·23은 제외한다. 따라서 22.11 이상을 모든 뒤 major까지 이어지는 연속 범위로 해석하지 않는다.

먼저 업그레이드 전 증거를 남긴다. 명령은 모두 앱 루트에서 시작한다.

node --version
npm --version
java -version
xcodebuild -version
npm test -- --runInBand
npm run android
npm run ios

npm run android는 Android emulator 또는 연결한 기기에서, npm run ios는 iOS Simulator에서 앱이 시작되는지 확인한다. 순정 RnDiffApp 연습에서는 명령의 종료 코드와 기본 시작 화면만 기록한다. 7편 모듈이나 10편 저장 fixture를 실제로 포함한 제품 앱의 검증은 뒤에서 별도 확장으로 구분한다.

잘못된 첫 시도는 Upgrade Helper에서 package.json 부분만 적용하는 것이다. react-native와 @react-native/* 패키지를 0.85.0에 맞추고 새 @react-native/jest-preset도 설치한다. 설치는 끝날 수 있지만 jest.config.js는 여전히 다음과 같다.

npm install [email protected] @react-native/[email protected]
npm install --save-dev \
  @react-native/[email protected] \
  @react-native/[email protected] \
  @react-native/[email protected] \
  @react-native/[email protected] \
  @react-native/[email protected]

Jest는 JavaScript test를 실행하는 도구이고, preset은 그 도구에 필요한 변환·실행 설정을 미리 묶은 값이다. 아래 module.exports는 설정 객체를 내보내는 CommonJS 모듈 문법이다.

module.exports = {
  preset: 'react-native',
}

실행 전에 예측한다.

1. 새 preset 패키지를 설치하기만 하면 Jest가 설정 문자열도 자동으로 바꿀까?
2. npm install 성공은 Android Gradle과 iOS Ruby 의존성이 목표 상태라는 증거일까?
3. JavaScript 테스트 하나가 실패하면 Android와 iOS 차이는 조사하지 않아도 될까?

0.85는 Jest preset을 react-native 패키지 밖으로 옮겼다. 따라서 이전 설정에서 npm test -- --runInBand를 실행하면 Jest가 react-native preset을 찾지 못하고 종료한다. 설치 성공은 패키지 파일을 내려받았다는 증거일 뿐 세 프로젝트 정렬의 증거가 아니다.

지원 버전은 목표 후보이지 앱 호환성 증명이 아니다

Active는 해당 React Native minor 계열에 정기적인 수정이 제공되는 지원 상태다. End of Cycle은 Active보다 패치가 줄어든 지원 주기 말기이며 이후 Unsupported로 이동한다. Future는 아직 정식 출시 전인 다음 후보를 뜻한다. 앱이 사용하는 카메라 SDK, 알림 모듈, 분석 SDK와 사내 네이티브 모듈이 모두 호환된다는 뜻은 아니다. Android Gradle Plugin(AGP)은 Gradle에 Android 전용 빌드 규칙을 더하는 플러그인이다. 목표를 다음처럼 기록한다.

순정 RnDiffApp에는 다음 두 행이 없다. 실제 제품 앱에서만 별도 호환성 표에 추가한다.

여기서 네이티브 모듈은 JavaScript 호출을 Android·iOS 구현에 연결하는 패키지나 사내 코드다. “지원됨” 칸을 추정으로 채우지 않고 근거가 없으면 미확인으로 남긴다.

따라서 0.84→0.85를 일반적인 1.x 라이브러리의 작은 기능 추가와 같은 뜻으로 읽지 않는다. 버전 숫자는 조사 범위를 알려 주고, 실제 해야 할 일은 해당 구간의 공식 문서와 diff가 정한다.

설치 성공은 세 프로젝트의 정렬을 증명하지 않는다

package.json / lockfile
  └─ JavaScript·Metro·Jest·Codegen 패키지
 
android/
  └─ Gradle wrapper·plugin·SDK·JDK·네이티브 모듈
 
ios/ + Gemfile
  └─ Ruby 도구·CocoaPods·Xcode 프로젝트·네이티브 모듈

세 영역은 연결되지만 같은 검사로 증명되지 않는다. TypeScript 성공은 Kotlin 컴파일을 실행하지 않고, Android 빌드는 CocoaPods가 만든 iOS 의존성 그래프를 읽지 않는다.

Upgrade Helper를 해야 할 일 목록으로 바꾼다

0.85 release note와 Upgrade Helper를 다음 체크리스트로 바꾼다.

Jest 교정은 다음 한 줄이다.

 module.exports = {
-  preset: 'react-native',
+  preset: '@react-native/jest-preset',
 }

같은 실패 명령을 즉시 다시 실행한다.

npm test -- --runInBand

순정 RnDiffApp의 기본 App test가 통과하고 명령이 종료 코드 0을 반환해야 Jest 교정이 닫힌다. 이 결과만으로 Android와 iOS까지 맞았다고 결론 내리지는 않는다.

공식 template을 앱에 통째로 덮어쓰지는 않는다. 앱이 추가한 배포 서명, 플랫폼별 빌드 단계, 권한과 네이티브 SDK 설정을 잃을 수 있다. 각 target diff를 적용, 앱 고유 설정 때문에 변형, 의도적으로 유지 중 하나로 분류하고 뒤의 두 경우에는 이유와 검증 증거를 남긴다.

Android는 Gradle 하나가 아니라 호환 조합으로 본다

Gradle은 Android 빌드 작업을 실행하는 도구이고, Android Gradle Plugin(AGP)은 그 위에 Android 전용 빌드 규칙을 더하는 플러그인이다. Gradle wrapper는 저장소에 기록된 버전으로 Gradle을 실행하는 script와 설정 묶음이다.

JDK(Java Development Kit)는 Gradle과 Android의 Java·Kotlin 빌드에 필요한 Java 도구 모음이다. NDK(Native Development Kit)는 C·C++ 네이티브 코드를 Android용으로 만드는 도구이고, CMake는 그 네이티브 빌드 구성을 생성한다. compileSdk는 컴파일에 쓸 Android API, targetSdk는 앱이 대상으로 선언한 Android 동작 수준, minSdk는 설치를 허용할 최소 Android API다.

0.85 template이 wrapper를 9.3.1로 바꿨다는 사실만 보고 모든 앱에 같은 한 줄만 강제로 복사하지 않는다. target template diff를 출발점으로 삼고 다음을 함께 기록한다.

Gradle wrapper version
Android Gradle Plugin version
React Native Gradle Plugin version
JDK version
compileSdk / targetSdk / minSdk
NDK·CMake를 직접 쓰는 모듈의 버전

그 뒤 앱 루트에서 Android 폴더로 이동해 wrapper와 두 build 구성을 실행한다.

cd android
./gradlew --version
./gradlew :app:assembleDebug
./gradlew :app:bundleRelease
cd ..
npm run android

assembleDebug 성공은 개발용 네이티브 앱을 만들었다는 증거이고, bundleRelease 성공은 Android App Bundle(AAB, Google Play에 올리는 Android 앱 코드·자원 묶음 파일 형식)을 만들 수 있다는 증거다. npm run android로 같은 target 앱의 기본 화면이 emulator에 나타나는 것까지 확인한다. 하나가 다른 하나를 자동으로 포함한다고 가정하지 않는다. 배포 서명 키나 환경 변수가 필요한 앱은 Continuous Integration(CI, 변경을 자동 검사하는 지속적 통합 환경)에도 같은 release 입력을 제공한다.

iOS는 Ruby 설치와 Pod 해석 뒤에야 빌드한다

CocoaPods는 iOS·macOS 네이티브 의존성을 프로젝트에 통합하는 패키지 관리 도구다. Gemfile은 CocoaPods 같은 Ruby 도구 버전을, Podfile은 앱에 연결할 iOS 네이티브 의존성과 설정을 선언한다.

0.85 target Gemfile 차이를 적용한 뒤 앱 루트와 ios 폴더의 작업 위치를 구분한다.

# 앱 루트: Gemfile과 Gemfile.lock 기준 Ruby 도구 설치
bundle install
 
# ios 폴더: Podfile과 Podfile.lock 기준 iOS 네이티브 의존성 통합
cd ios
bundle exec pod install

그 다음 CocoaPods가 만든 .xcworkspace를 사용해 Debug와 Release를 각각 빌드한다. 프로젝트 이름과 scheme은 실제 앱 값으로 바꾼다. scheme은 어떤 target과 build 설정을 함께 실행할지 정한 Xcode의 빌드 이름이다.

xcodebuild \
  -workspace RnDiffApp.xcworkspace \
  -scheme RnDiffApp \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination 'generic/platform=iOS Simulator' \
  CODE_SIGNING_ALLOWED=NO build
 
xcodebuild \
  -workspace RnDiffApp.xcworkspace \
  -scheme RnDiffApp \
  -configuration Release \
  -sdk iphonesimulator \
  -destination 'generic/platform=iOS Simulator' \
  CODE_SIGNING_ALLOWED=NO build
 
cd ..
npm run ios

두 xcodebuild 명령은 Simulator용 Debug·Release 컴파일과 링크를 증명하고, npm run ios는 기본 화면 시작을 확인한다. App Store 제출용 앱 묶음인 archive와 실기기 배포 서명을 증명하지는 않으므로 배포 경로에서는 Xcode의 Release scheme과 실제 배포 서명을 별도로 확인한다.

네이티브 모듈은 이름이 아니라 사용 경계로 검증한다

이 절은 순정 RnDiffApp이 아니라 아래 fixture를 실제로 포함한 제품 앱의 추가 검증이다. 네이티브 모듈 목록을 단지 “설치됨”으로 표시하지 않고, 각 모듈이 어느 플랫폼 파일, 권한, Codegen Spec과 운영체제 기능에 닿는지 적는다.

10편의 저장 fixture도 업그레이드 입력에 포함한다. 새 설치에서 빈 저장소만 확인하면 이전 바이너리가 남긴 V1을 놓친다. 0.84 앱에서 V1을 저장한 상태로 0.85 앱을 덮어 설치해 V2로 한 번만 옮겨지고, 같은 앱을 다시 열 때 불필요한 재저장이 없는지 확인한다.

프레임워크 업그레이드와 저장 형식 변경을 같은 배포에 섞을 이유가 없다면 분리한다. 함께 바꿔야 한다면 이전 바이너리로 되돌릴 때 새 형식을 읽을 수 있는지까지 출시·롤백 조건에 넣는다.

Android와 iOS의 증거를 각각 쌓는다

검증은 싼 증거부터 실패 범위를 좁힌다.

1. 기준선: 이전 버전의 test, 양쪽 build·start와 핵심 흐름을 같은 환경에서 기록한다.
2. diff 완결성: release note와 Upgrade Helper 항목을 적용·변형·유지로 모두 분류한다.
3. JavaScript 도구: 깨끗한 package 설치, lockfile 검토, lint·type·Jest를 실행한다.
4. Android build: wrapper version, Debug와 Release build를 확인한다.
5. iOS build: Ruby 설치, Pod 설치, Debug와 Release build를 확인한다.
6. 순정 fixture 실행: emulator와 Simulator에서 RnDiffApp 기본 화면을 확인한다.
7. 제품 앱 확장: 해당 앱에 실제로 있는 NativeReceiptStore와 V1 복원 fixture를 양쪽에서 확인한다.
8. 실기기 경계: 실제 장치 능력에 닿는 변경만 지원 기기에서 핵심 흐름을 실행한다.
9. 배포 산출물: CI의 배포 서명·환경 변수로 만든 AAB와 iOS archive를 배포 전 검증한다.

한 단계가 실패하면 그 아래의 더 비싼 검증으로 넘어가지 않는다. 반대로 JavaScript test가 초록색이라고 Android·iOS 단계를 생략하지 않는다.

가상 환경과 실기기 검증 범위를 위험에 맞춘다

이 글의 0.84→0.85 Jest 실패와 template diff 자체는 가상 환경과 양쪽 build로 재현할 수 있다. 실기기 검증이 필요한지는 앱이 실제로 사용하는 네이티브 모듈과 변경 경계가 정한다. 모든 화면을 무작정 반복하는 것도, “Simulator에서 켜졌다”만으로 실제 장치 경계를 통과했다고 보는 것도 피한다.

실기기에서는 개인 알림·계정·사진이 섞이지 않은 전용 test 계정과 장치를 사용하고, 검증한 모듈과 OS·기기 조합을 결과에 기록한다.

순정 RnDiffApp 교정의 최종 기록은 다음처럼 닫힌다. 제품 앱 확장 증거는 실제 fixture가 있는 경우에만 별도 행으로 추가한다.

Jest 기본 App test                 성공
Android assembleDebug              성공
Android bundleRelease              성공
Android emulator 기본 화면         표시됨
iOS Simulator Debug build          성공
iOS Simulator Release build        성공
iOS Simulator 기본 화면            표시됨

같은 상황을 다시 진단한다

문제       package.json을 0.85로 바꾼 뒤 Jest preset을 찾지 못하고 종료
잘못된 판단 npm install이 성공했으므로 React Native 업그레이드 완료
관찰       0.84→0.85 공식 diff에는 Jest·Gradle wrapper·Gemfile 변화가 함께 있음
원인       JavaScript package만 바꾸고 target 생성 프로젝트 입력을 정렬하지 않음
행동       release note·Upgrade Helper 항목을 세 프로젝트에 적용하고 앱 사용자 정의와 병합
검증       Jest → Android/iOS build → 양쪽 시작·핵심 모듈 → release·위험 기반 실기기

풀 리퀘스트에서는 다음을 확인한다.

• 현재와 목표 React Native 지원 상태를 확인한 날짜가 있는가?
• React Native·React·@react-native/*와 lockfile의 실제 선택 버전이 목표 조합인가?
• Upgrade Helper의 모든 파일을 적용·변형·유지 중 하나로 분류했는가?
• Android의 Gradle·AGP·React Native plugin·JDK·SDK 조합을 기록했는가?
• iOS의 Gemfile.lock·Podfile.lock과 .xcworkspace build를 확인했는가?
• 양 플랫폼에서 사용하는 Codegen·네이티브 모듈을 실제 호출했는가?
• 이전 앱이 만든 저장 데이터를 새 앱이 읽고, 필요하면 되돌릴 조건도 확인했는가?
• Debug뿐 아니라 CI와 같은 Release 산출물을 만들었는가?
• 실제 장치 기능에 닿는 변경만 명확한 실기기 test로 닫았는가?

12편에서는 앱 안 WebView가 React Native JavaScript와 왜 별도 실행환경인지, 같은 변수나 함수에 직접 접근할 수 없다는 경계를 한 질문으로 다룬다.

한 문장으로 다시 설명하기

React Native 업그레이드는 package 버전을 올리는 일이 아니라 공식 두 버전의 차이로 JavaScript, Android와 iOS 프로젝트를 같은 목표 조합에 정렬하고, 각 플랫폼의 build·시작·핵심 네이티브 동작과 release 산출물을 독립 증거로 다시 세우는 일이다.

스스로 확인하기

1. 왜 npm install 성공은 React Native 업그레이드 완료 증거가 아닌가?
2. 지원 표의 Active와 현재 앱의 네이티브 모듈 호환성은 어떻게 다른가?
3. Upgrade Helper의 target template diff를 통째로 덮어쓰지 않고 분류해야 하는 이유는 무엇인가?
4. Android에서 Gradle wrapper·AGP·JDK·SDK를 함께 보는 이유는 무엇인가?
5. iOS에서 bundle install과 bundle exec pod install은 각각 어떤 입력을 해석하는가?
6. Android 성공이 iOS 성공을 대신하지 못하는 이유는 무엇인가?
7. 10편의 V1 저장 fixture가 프레임워크 업그레이드 검증에도 필요한 이유는 무엇인가?
8. 어떤 네이티브 변경을 실기기에서 확인해야 하는가?