왜 업그레이드를 하게 되었나

현재 회사에서 운영 중인 앱의 React Native 버전은 0.75.2였다. 새로 개발할 PoC 앱을 기존 앱에 통합하려는 계획이 있었다. 쉽게 말하면 슈퍼앱(여러 서비스를 하나에 묶는 형태)처럼 마이크로 프론트엔드 아키텍처를 활용해서 하나의 앱 안에 여러 독립적인 서비스를 넣는 방식이었다.

repack-minimum-requirementsreact-native-devtools-minimum-requirements

이를 위해 조사하던 중 [re.pack]이라는 도구를 발견했는데, 문제가 하나 있었다.re.pack의 최소 요구 버전이 React Native 0.77 이상이었다. 게다가 개발 생산성을 높이기 위해 사용하고 싶었던 React Native DevTools도 0.76 버전 이상부터 지원되었다.

React Native 버전은 계속 올려나가야 했다. 최신 iOS와 Android의 요구사항을 충족하고, 앱 심사 과정에서 발생할 수 있는 버전 관련 이슈를 미리 방지하기 위해서라도 업데이트는 필수였다. 또한 보안 패치와 성능 개선, 새로운 기능 지원을 받기 위해서도 주기적인 버전 업데이트가 중요했다.

그래서 버전을 올릴 거라면 0.77.2로 맞추기로 결정했다. 조사 결과 0.77.2 버전부터 안정적이라는 피드백을 여러 곳에서 확인할 수 있었다.

React Native 0.76 ~ 0.77의 주요 변화

업그레이드를 시작하기 전에 무엇이 바뀌었는지 먼저 파악해야 했다. React Native의 새로운 아키텍처인 JSI, Fabric, TurboModules는 0.68 버전(2022년 3월)부터 opt-in 방식으로 지원되기 시작했다. 하지만 기본값은 아니었고, 사용하려면 직접 활성화해야 했다.

0.76에서 달라진 점

• 새로운 아키텍처가 기본값으로 전환: 더 이상 opt-in이 아니라 모든 새 프로젝트에서 기본적으로 활성화됨
• 프로젝트 템플릿 구조 대폭 개편: 기존 구조와 많이 달라져서 설정 파일 변경 사항이 많음
• React Native DevTools 도입: 공식 디버깅 도구가 추가됨
• Metro 번들러 개선: 리졸버 성능이 약 15배 향상되어 빌드 속도가 빨라짐

0.77에서 달라진 점

• 새로운 아키텍처의 안정화 및 버그 수정
• 레거시 코드 제거 및 정리
• 성능 최적화 지속

왜 Breaking Changes가 많았을까?

0.75에서 0.77로 업그레이드하면서 많은 패키지 호환성 문제가 발생했다. 그 이유는:

• 새로운 아키텍처 전환: 많은 서드파티 라이브러리들이 새로운 아키텍처를 지원하도록 업데이트되어야 했음
• 네이티브 빌드 설정 변경: iOS의 CocoaPods, Android의 Gradle 설정이 크게 바뀜
• deprecated API 제거: 오래된 API들이 제거되면서 이에 의존하던 패키지들이 영향을 받음
• 의존성 최소 버전 상향: Node, Ruby, Java, Xcode 등의 최소 버전이 높아짐

마이그레이션 시작

react-native-document

우선 React Native 공식 문서부터 찾아봤다. Workflow 탭의 "Upgrading to new versions" 페이지에서 Upgrade Helper라는 사이트를 추천하고 있었다.

Upgrade Helper 사용

upgrage-helper-site

Upgrade Helper에서는 프로젝트명, 현재 버전, 업그레이드할 버전을 입력하면 어떤 파일들을 어떻게 수정해야 하는지 diff 형태로 보여준다. 입력하고 나니 총 21개의 파일에 대한 추가, 수정, 삭제가 필요했다. 하나하나 수정을 진행하면서 몇 가지 주의할 점을 발견했다.

upgrade-helper-example

iOS 번들 방식 변경

README.md 파일의 수정 내용을 보면 iOS 번들하는 방법이 바뀐 것을 확인할 수 있었다. 기존에는 프로젝트 내 ios 폴더에 진입해서 pod install만 하면 됐는데, 이제는 Ruby bundler를 사용하는 방식으로 변경되었다.

# 새로운 방식
bundle install
bundle exec pod install

RnDiffApp 주의사항

"RnDiffApp"은 예시 프로젝트명이고, 이 부분은 내 프로젝트명으로 바꿔서 적용해야 한다. 나는 이 부분을 그대로 하드 카피했다가 어디서 에러가 발생하는지 몰라서 한참을 헤맸다. 정말 시간 낭비였다...

파일 삭제 시 경로 확인

파일을 삭제할 때도 경로를 잘 살펴봐야 한다. 파일명이 동일한 파일들이 여러 곳에 존재하기 때문에 경로를 정확히 확인하고 삭제해야 한다.

빌드하며 패키지 호환성 맞추기

Upgrade Helper에서 제시한 파일들을 모두 수정했다. 여기까지가 React Native의 버전을 업그레이드 하는 작업을 완료한 것이며, 그 다음엔 다음과 같은 방식으로 빌드를 진행한다.

[1] 기존 package-lock.json과 node_modules를 삭제한다.

[2] npm install을 다시 실행한다.

[3] ios와 android를 각각 빌드한다.

첫 번째 빌드 시도

iOS 빌드를 실행해봤다.

rm -rf Pods Podfile.lock build # 확실하게 하기 위해서 기존 빌드 파일들 삭제
 
bundle install && cd ios && bundle exec pod install

그리고 바로 에러가 발생했다.

error /Users/yh/MyProject/OneRM/node_modules/react-native-svg/apple/Filters/MetalCI/RNSVGArithmeticFilter.iphoneos.metallib: No such file or directory (in target 'RNSVG-RNSVGFilters' from project 'Pods')
error Failed to build ios project. "xcodebuild" exited with error code '65'.

react-native-svg 패키지에서 에러가 발생하고 있었다.

패키지 호환 버전 찾기

React Native 0.77.2와 호환되는 react-native-svg 버전을 찾아야 했다.

react-native-svg-releases

보통 패키지의 공식 문서나 GitHub README에 React Native 버전별 호환 버전이 명시되어 있다. 하지만 react-native-svg는 그런 정보가 명확하지 않아서 react-native-svg의 GitHub 릴리즈 페이지를 직접 확인했다.

v15.11.0부터 React Native@0.77과 호환이 되었지만 v15.11.0 에 대한 Hotfix가 존재하여 v15.11.1을 사용하였다.

반복되는 과정

그리고 또 다른 패키지에서 에러가 발생했다. 에러가 발생한 패키지의 호환되는 버전을 찾아서 변경하고 빌드하는 이 과정을 계속 반복했다.

[1] package.json에서 패키지 버전 변경

[2] package-lock.json과 node_modules 삭제

[3] iOS는 bundle exec pod install 진행 후 npm run ios 실행

[4] Android는 별도 설치 없이 npm run android 실행 (서버 실행 시 자체적으로 빌드가 진행됨)

[5] 에러 발생하면 1번부터 반복

에러가 나올 때마다 해당 패키지를 찾아서 0.77 버전과 호환되는 버전으로 수정하고, 다시 빌드하는 과정을 여러 번 반복했다.

배운 점

1. Upgrade Helper는 정말 유용하다

React Native 공식 문서에서 추천하는 Upgrade Helper는 정말 큰 도움이 되었다. 어떤 파일을 수정해야 하는지 한눈에 볼 수 있어서 놓치는 부분 없이 작업할 수 있었다.

2. RnDiffApp을 그대로 복사하지 말자

이건 정말 중요하다. Upgrade Helper에서 보여주는 "RnDiffApp"은 예시일 뿐이고, 실제로는 내 프로젝트명으로 바꿔야 한다. 이 부분 때문에 시간을 많이 낭비했다.

3. 패키지 호환성은 하나씩 확인해야 한다

React Native 버전을 올리면 설치된 패키지들도 함께 업데이트해야 한다. 각 패키지의 릴리즈 노트나 GitHub 페이지를 확인해서 호환되는 버전을 찾는 과정이 필요하다.

4. 빌드 - 에러 확인 - 수정의 반복

한 번에 모든 패키지를 업데이트하기보다는, 빌드를 해보고 에러가 나는 패키지부터 하나씩 수정하는 게 더 효율적이었다. 어떤 패키지에서 문제가 생기는지 명확하게 파악할 수 있기 때문이다.

5. iOS와 Android 빌드 방식이 다르다

iOS는 bundle exec pod install 과정이 필요하지만, Android는 서버 실행 시 자체적으로 빌드가 진행된다. 이런 차이를 이해하고 있으면 트러블슈팅이 훨씬 수월하다.

요약

마이크로 프론트엔드 아키텍처 도입을 위해 React Native를 0.75.2에서 0.77.2로 업그레이드했다. Upgrade Helper를 활용해서 React Native 버전 업그레이드를 위해서 21개의 파일을 수정했고, 빌드 과정에서 발생하는 패키지 호환성 문제를 하나씩 해결해나갔다. RnDiffApp을 그대로 복사하는 실수로 시간을 낭비하기도 했지만, 결국 성공적으로 업그레이드를 완료했다. 앞으로는 패키지 버전 표기법을 더 잘 활용하고, 주기적인 버전 업데이트를 통해 기술 부채를 줄여나갈 계획이다.