react-native 버전 업그레이드 가이드, v0.69 to v0.78

📒 react-native 버전 업그레이드 가이드, v0.69 to v0.78

---

최근에 현재 개발하는 리액트 네이티브 앱의 버전을 업그레이드하는 업무를 맡게 되었습니다.
리액트 네이티브 버전 업은 평소에도 악명이 자자해서 지래 겁부터 먹었지만, 생각보다 일정을 넉넉하게 받게 되어 차근차근 버전을 올리다 보니 0.69 버전에서 0.78 버전까지 올리게 되었습니다. 이왕 하는 거 기존에 호환성 문제 때문에 런타임 에러를 유발하던 Hermes 엔진도 enable 한 뒤 어느 정도 런타임 에러도 잡았겠다, 마냥 두려워했던 RN 버전 업그레이드에 대한 가이드를 작성해보려 합니다.
 

📌 전략 세우기

RN 버전을 올린다는 것은 바뀐 네이티브 코드들을 반영하고 패키지 버전을 맞춰주는 게 알파이자 오메가인 작업입니다.
제가 지금 개발하고 있는 앱의 경우 히스토리가 굉장히 오래되었고, 그동안 여러 SDK들과 설정들로 인해 네이티브 코드들이 기존과 상당히 달라진 상태였습니다. 버전을 올리려면 바뀐 네이티브 코드들을 반영하는 작업들이 가장 중요한데 이러한 히스토리들이 쌓여있다 보니 한 번에 많은 버전을 올려 많은 변경점들을 한 번에 적용하는 것은 무리가 있다고 판단했습니다.
그래서 저는 여러 버전들을 조사한 뒤 변경점이 유사한 버전들을 묶고, 점진적으로 버전을 올리는 방식을 사용했습니다.
만약 네이티브 코드들의 수정이 거의 없고, 패키지 의존성이 적은 상태라면 변경점을 반영하기 쉬우니 한 번에 높은 버전으로 뛰어넘는 것을 추천드립니다.
 

📌 버전 별 변경점

버전 별 큼지막한 변화들을 정리해봤습니다.

버전	AOS min.	IOS min.	변경점
0.78	Android 7.0(API 24)	15.1	react 19
0.77	Android 6.0(API 23)	13.4	objective-c → swift 기본 템플릿 변경 main.m, AppDelegate.h, AppDelegate.mm → AppDelegate.swift로 통합 반드시 마이그레이션 하지 않아도 됨
0.76	Android 6.0(API 23)	13.4	New Architecture 기본 적용 react-native-cli deprecated @react-native-community/cli 설치 필요
0.74	Android 6.0(API 23)	13.4	PushNotificationIOS 업데이트를 포함한 일부 중단 변경 PropTypes API 제거 Flipper 제거
0.73	Android 5.0(API 21)	13.4	Android 기본 언어 Kotlin으로 변경, 반드시 마이그레이션 필요 X Deprecated @types/react-native 타입정보 react-native에서 기본 제공 metro-react-native-babel-preset → @react-native/babel-preset
0.72	Android 5.0(API 21)	12.4	새로운 메트로 구성 설정 주요 패키지 변경점

 
제가 0.69 -> 0.70 -> 0.72 -> 0.76 -> 0.77 -> 0.78 순으로 버전을 올려본 결과 0.72 버전과 0.76 버전만 뚫으면 의존성과 네이티브 코드의 변화는 미미한 수준이어서 다음 버전으로 나아가는데 큰 무리가 없었습니다.
가장 마음에 걸리는 것은 네이티브 코드 언어 변경인데, 안드로이드는 GPT의 도움으로 무난하게 Java에서 Kotlin으로 마이그레이션 했지만, IOS는 이미 objective-c로 작성된 네이티브 코드들을 마이그레이션 하기엔 무리가 있다고 판단해 그대로 사용 중입니다.
작동은 하지만 추후 버전을 무난하게 올리려면 마이그레이션을 미리 해두는 게 좋을 것 같습니다.
 

📌 버전 업 툴

버전 업을 하는데 가장 중요한 의존성과 네이티브 변경점을 확인할 수 있는 툴을 소개드립니다.

🔎 버전 별 의존성 버전 체크 및 변경

RN 버전에 따라 변경된 패키지 버전들을 확인하는 명령어입니다.
템플릿 package.json에 맞춰 버전을 체크해서, 반드시 버전을 올리지 않아도 되는 패키지들의 버전도 변경되기 때문에 마이그레이션이 필요한 패키지들은 이 명령어를 사용한 뒤 버전을 다시 되돌려주었습니다.

# 변경된 패키지 버전 확인
$ npx @rnx-kit/align-deps --requirements react-native@0.78

# 변경된 패키지 버전 package.json에 반영
$ npx @rnx-kit/align-deps --requirements react-native@0.78 --write

 
모든 패키지 버전을 체크하지는 않기 때문에 이 명령어를 사용한 뒤 다른 패키지들의 버전을 수동으로 버전을 맞춰주는 작업도 병행되어야 합니다.
 

🔎 React Native Upgrade Helper

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

Upgrade React Native applications

버전 업그레이드를 하는데 가장 중요하다고 볼 수 있는 웹페이지입니다.
현재 버전 템플릿과 목표하는 버전의 템플릿의 변경 전 후를 확인할 수 있습니다.

Android와 IOS의 네이티브 코드들을 하나씩 살피며 바꿔줍니다.
사소한 것 하나로 빌드 에러를 낼 수 있기에 가장 힘들고 꼼꼼하게 해야 하는 작업입니다.
정신 똑바로 차리고 한 줄 한 줄 정성스럽게 옮겨주도록 합니다.
 

📌 각종 캐시 삭제 명령어

버전을 올릴 땐 캐시에 의한 에러가 자주 발생하니, 빌드 단계에서 에러가 발생했다 하면 파블로프의 개처럼 캐시 먼저 지워주도록 합니다.

🔎 metro

$ yarn start --reset-cache

 

🔎 Android

$ cd android && ./gradlew clean

 

🔎 IOS

$ cd ios &&  
  rm -rf Pods && 
	rm -rf Podfile.lock &&
	rm -rf build &&
	pod repo remove trunk &&
	pod cache clean --all &&
	pod install

 
 

📌 빌드 에러 유발 패키지

지옥 1번 타자 빌드에러입니다.
얘는 그나마 어떤 패키지가 에러를 내는지 확실하게 알 수 있어서 런타임 에러보다는 양반입니다.
정말 수많은 패키지들에 의해 빌드 에러 고통을 받았지만 마이너 한 것들은 제끼고 대표적인 몇몇 개만 소개드립니다.
 

🔎 react-native-reanimated (모든 버전 유의)

애니메이션 관련 여러 패키지들이 의존하고 있는 유명한 라이브러리입니다.

https://docs.swmansion.com/react-native-reanimated/docs/guides/compatibility/
위 사진으로도 알 수 있듯 RN 버전에 따라 혹은 New Architecture에 따라 지원하는 버전이 모두 다르니 반드시 확인하고 설치해야 합니다.
 

🔎 react-native-google-mobile-ads (AOS / v0.72, v0.76)

인앱 광고 관련 패키지입니다.
0.72에서 ^11.0.0, 0.76에서 ^14.0.0 버전으로 올려 안드로이드 빌드 에러를 잡았습니다.
 

🔎 react-native-iap (AOS / v0.76+)

유명한 스토어 결제 패키지입니다.
0.76 버전에서 안드로이드 빌드 에러를 발생시켜 ~12.13.0 -> ~12.16.0 버전으로 올렸습니다.
그리고 버전을 올리며 안드로이드 구독 결제 인터페이스가 변경되어 런타임 에러를 유발하니 참고 바랍니다.

🔎 react-native-progress (v0.76+)

@react-native-community/art deprecated로 인한 빌드 에러로 ^4.0.0 -> ^5.0.0 버전으로 올렸습니다.
 

🔎 @supersami/rn-foreground-service (AOS / v0.76+)

symbol: variable drawable
location: class R
패키지 안드로이드 코드에서 빌드 에러를 유발해 patch-package로 에러를 잡았습니다.
자세한 내용은 다음 링크를 참고해 주세요.
https://github.com/Raja0sama/rn-foreground-service/issues/86#issuecomment-1920907971
 

🔎 @react-native-firebase/crashlytics (IOS xcode 16 / v0.76)

이건 xcode15에서 IOS 빌드 성공을 한 후 xcode16 버전을 올린 뒤 발생한 빌드 에러입니다.
그런데 아직 정확한 원인은 알 수 없어서 RN 버전 때문인지 xcode 버전 때문인지 알쏭달쏭합니다.
ios/connecting.xcodeproj/project.pbxproj에서 run script를 수정한 뒤 빌드 에러를 잡을 수 있었습니다.

- shellScript = "${PODS_ROOT}/Fabric/run\"\n";
+ shellScript = "${PODS_ROOT}/FirebaseCrashlytics/run\"\n";

 
 
 
 

📌 런타임 에러 유발 패키지

빌드가 끝났다고 안심하긴 이릅니다.
안드로이드가 실행된다고 IOS가 정상 실행 되는 것도 아닙니다.
2번 타자 런타임 에러, 큼지막한 것들 위주로 소개드립니다.

🔎 @react-navigation/* (v0.76+)

사실 RN 개발에선 빼놓을 수 없는 패키지입니다.
기존에 5 버전을 사용하고 있었는데 0.76 버전에서는 네비게이션이 의존하고 있는 패키지 때문인 건지 런타임 에러를 발생시켰습니다.
7 버전으로 가기에는 변경점들이 너무 많아 6 버전으로 올린 뒤 변경점을 반영해서 에러를 해결했습니다.
 

🔎 reactotron-react-native (v0.72+)

RN 디버깅하는데 유용하게 사용하는 reactotron입니다.
앱 시작하자마자 에러를 뱉고, 에러 스택은 "번들 파일의 redux store가 undefined" 라고만 보여줘서 가장 난감했던 순간이었습니다.
RN 버전을 올리며 redux store가 초기화되기 전 reactotron에서 참조했기 때문이라고만 추측될 뿐입니다.
자료 하나 없이 번들 파일 하나로 어찌저찌 추리하며 reactotron 버전을 3.4.0 -> ^5.0.0으로 올려 에러를 해결했습니다.
 

🔎 @welldone-software/why-did-you-render (v0.78+)

react 19로 인한 런타임 에러를 발생시켜 ^10.0.0 버전으로 올려 해결했습니다.
https://github.com/welldone-software/why-did-you-render/releases/tag/v10.0.0
 

🔎 react-native-code-push

https://github.com/microsoft/react-native-code-push#supported-react-native-platforms
RN 버전별로 지원하는 코드푸시 패키지 버전이 다르니 잘 설정해 줍니다.
저는 7 버전에서 8 버전으로 올렸는데 하위 호환 지원이 잘 되는지 큰 문제가 없어 보이네요.
 

📌 후기

지금은 혹시 모를 에러에 대비해서 안정화 단계를 거치고 있습니다.
이제 와서 생각해 보면 할 수 없을 것만 같았던 것을 성공 근처까지 왔다는 게 믿기지 않네요.
사람은 적응의 동물이라고 버전 업도 하면 할수록 실력이 늘어가는 게 신기하기도 합니다.
안드로이드, IOS와 지지고 볶고 하다 보니 네이티브 단의 이해도 많이 늘어난 것 같고, 많은 패키지들을 까보고 patch-package 하다보니 어떤 에러를 만나도 해결할 수 있을 것 같은 자신감도 생겼습니다.
이제 막 버전 업을 하신 분들은 걱정이 앞서겠지만 그래도 "하면 된다"라고 말씀드리고 싶네요.
파이팅