React Native New Architecture 마이그레이션, 어디서부터 확인해야 할까

😀 개요

안녕하세요 😀

지난 글(「React Native 0.82부터 레거시 아키텍처를 못 쓰는 이유」 )에서 React Native 0.82부터 New Architecture가 유일한 아키텍처가 됐다는 이야기를 정리하면서, 다음 글에서는 실제 프로젝트를 넘길 때 어떤 라이브러리를 먼저 확인하고 체크리스트를 어떻게 잡으면 좋을지 다루겠다고 예고했습니다.

이번 글이 그 마이그레이션 편입니다.

New Architecture가 기본값이 됐다는 소식을 듣고 프로젝트에서 한번 켜 본 분들이 많을 텐데요. 이때 자주 겪는 상황이 이렇습니다.

• 앱은 빌드됐는데 특정 화면에서 네이티브 뷰가 안 보인다.
• pod install이나 Gradle 빌드 단계에서 처음 보는 에러가 난다.
• 잘 쓰던 서드파티 라이브러리가 New Architecture에서 동작하지 않는다.

저도 처음 관련 문서를 볼 때 "그냥 버전만 올리면 되는 거 아닌가?"라고 생각했습니다. 그런데 공식 문서를 따라가 보니, 마이그레이션은 버전을 올리는 작업이라기보다 내 프로젝트가 쓰는 것들이 New Architecture에서도 동작하는지 하나씩 확인하는 작업에 가까웠습니다.

🎯 이 글을 끝까지 읽으면

이 글을 다 읽으면 아래 세 가지가 정리됩니다.

• 내 프로젝트를 지금 옮길지, 조금 기다릴지 판단하는 기준
• 무엇을 어떤 순서로 확인하고 전환해야 하는지에 대한 체크리스트
• 라이브러리·빌드에서 자주 막히는 지점과, 그때 어디를 봐야 하는지

즉, "일단 최신 버전으로 올린다"가 아니라 막히는 지점을 미리 알고 순서대로 접근하는 방법을 챙겨 가는 것이 목표입니다.

🧭 먼저, 이 글의 근거 범위

시작하기 전에 한 가지 분명히 하겠습니다.

이 글은 제가 특정 상용 프로젝트를 New Architecture로 직접 마이그레이션한 경험담이 아니라, React Native 공식 블로그와 문서를 기준으로 정리한 설명·결정 가이드입니다. 코드 예시는 문서 기준으로 재현 가능하게 적었지만, 버전·라이브러리 조합에 따라 결과가 달라질 수 있습니다.

 

🗺️ 마이그레이션 전체 흐름 먼저 보기

세부 단계로 들어가기 전에 큰 그림을 먼저 보겠습니다. 공식 블로그가 권장하는 흐름을 단순화하면 이렇습니다.

1. 현재 RN 버전과 사용 중인 라이브러리 목록 파악
2. 라이브러리별 New Architecture 지원 여부 확인
3. 중간 버전(예: 0.81 또는 Expo SDK 54)에서 New Architecture 활성화
4. iOS / Android 양쪽 빌드 확인
5. 자주 쓰는 화면 위주로 QA
6. 문제가 없으면 0.82 이상으로 업그레이드 검토

 

여기서 핵심은 순서입니다. 3번(활성화)부터 시작하는 분이 많은데, 실제로 시간을 잡아먹는 건 대부분 1~2번을 건너뛰었을 때입니다. 쓰는 라이브러리를 모르는 상태에서 버전을 올리면, 어디가 원인인지 찾는 데만 하루가 갑니다.

참고로 공식 블로그는 아직 New Architecture로 넘어가지 않은 프로젝트라면, 0.82로 바로 점프하기보다 0.81 또는 Expo SDK 54에서 먼저 New Architecture를 켜서 확인한 뒤 올리는 흐름을 권장합니다.

🔎 1단계 — 내가 뭘 쓰고 있는지부터 확인하기

가장 먼저 할 일은 현재 상태 파악입니다. RN 버전은 프로젝트 루트에서 바로 확인할 수 있습니다.

# 현재 설치된 React Native 버전
npx react-native --version

# package.json에 적힌 버전
cat package.json | grep react-native

그다음이 더 중요합니다. 네이티브와 강하게 연결된 라이브러리 목록을 뽑는 일입니다.

# 의존성 목록에서 네이티브 관련 라이브러리를 눈으로 훑어봅니다
npm ls --depth=0

이 중에서 특히 아래 성격의 라이브러리를 표시해 두세요. New Architecture 대응 여부에 따라 이슈가 생기기 쉬운 쪽입니다.

• 카메라 / 지도 / 결제 / 푸시 알림
• 생체 인증 / 파일 시스템 / 블루투스
• 화면 전환(navigation)·제스처·리애니메이션 계열
• 오래 업데이트가 멈춘 커스텀 네이티브 모듈

📚 2단계 — 라이브러리 호환부터 확인하기

라이브러리 목록을 뽑았다면, 각 라이브러리가 New Architecture를 지원하는지 확인합니다.

가장 편한 방법은 커뮤니티 디렉터리를 쓰는 것입니다. reactnative.directory에서는 라이브러리별로 New Architecture 지원 여부를 표시해 줍니다. 여기서 내가 쓰는 라이브러리를 하나씩 검색해 상태를 확인하면 됩니다.

 

이때 확인 결과를 표로 정리해 두면 마이그레이션 계획이 훨씬 선명해집니다.

라이브러리	현재 버전	New Arch 지원	조치
예: 카메라 라이브러리	[직접 확인]	지원/부분/미지원	최신화 / 대체 / 보류
예: 지도 라이브러리	[직접 확인]	[직접 확인]	[직접 확인]

쉽게 말하면, 여기서 "미지원"이 하나라도 있으면 그 라이브러리가 곧 마이그레이션의 병목입니다. 버전을 올리기 전에 최신 버전으로 갱신하거나, 대체 라이브러리를 찾거나, 해당 기능을 잠시 뒤로 미루는 결정을 먼저 해야 합니다.

🧩 3단계 — Interop Layer가 막아 주는 것과 못 막아 주는 것

여기서 많이 오해하는 부분이 있습니다. "라이브러리가 아직 New Architecture 전용으로 안 바뀌었으면 무조건 못 쓴다"고 생각하는 경우인데요, 꼭 그렇지는 않습니다.

New Architecture에는 Interop Layer(상호운용 계층)라는 것이 있습니다. 쉽게 말하면, 예전(Paper) 방식으로 만들어진 네이티브 모듈이나 뷰를 New Architecture 위에서도 어느 정도 그대로 동작하게 감싸 주는 호환 장치입니다. 덕분에 모든 라이브러리를 한 번에 다 바꾸지 않아도 마이그레이션을 점진적으로 진행할 수 있습니다.

다만 Interop Layer는 만능이 아닙니다. 공식 문서 기준으로 아래 같은 경우는 여전히 손이 필요할 수 있습니다.

• 복잡한 커스텀 네이티브 UI(뷰 매니저)를 쓰는 라이브러리
• 예전 구조의 세부 동작에 의존하던 모듈
• 이미 유지보수가 멈춘 오래된 라이브러리

그래서 접근 순서는 이렇게 잡는 편이 안전합니다. 먼저 Interop Layer에 기대어 앱을 돌려 보고, 실제로 깨지는 부분만 골라서 최신화하거나 교체하는 것입니다. 처음부터 전부 갈아엎으려고 하면 범위가 너무 커집니다.

🛠️ 자주 막히는 지점과 접근법

이제 실제로 자주 나오는 막힘을 정리해 보겠습니다. 아래는 공식 문서·이슈에서 반복적으로 언급되는 대표적인 유형이고, 구체적인 에러 메시지는 프로젝트마다 다를 수 있습니다.

① 서드파티 라이브러리가 화면에서만 안 보이거나 깨질 때

빌드는 되는데 특정 컴포넌트만 렌더링되지 않는다면, 그 컴포넌트를 제공하는 라이브러리가 New Renderer(Fabric)에 아직 대응하지 못했을 가능성이 큽니다.

• 먼저 해당 라이브러리의 최신 버전이 New Architecture 지원을 명시하는지 확인합니다.
• 최신 버전이 있으면 올려 보고, 없으면 대체 라이브러리 또는 임시 우회를 검토합니다.
•  어떤 라이브러리의 어떤 컴포넌트에서 발생했는지 기록해 두면 이후 판단이 쉬워집니다.

② 커스텀 네이티브 모듈에서 타입/Codegen 관련 에러가 날 때

직접 만든 네이티브 모듈이 있다면, New Architecture에서는 Codegen을 거치도록 바꿔야 하는 경우가 많습니다. Codegen은 쉽게 말하면 JavaScript와 Native 사이의 "타입 계약서"를 자동으로 만들어 주는 도구입니다. 예전에는 느슨하게 주고받던 값을, 이제는 명세(spec)에 맞춰 정확히 맞춰야 합니다.

• 모듈의 인터페이스를 spec 파일로 정의했는지 확인합니다.
• 빌드 에러에 타입 불일치나 Codegen 관련 메시지가 있으면, spec과 실제 구현이 어긋난 지점을 먼저 봅니다.
• 발생한 정확한 에러 메시지와 해당 모듈명을 캡처해 두세요.

③ 빌드 단계(pod install / Gradle)에서 막힐 때

버전을 올린 뒤 iOS의 pod install이나 Android Gradle 단계에서 막히는 경우도 흔합니다. 이때는 원인을 좁히기 위해 캐시와 산출물을 정리하고 다시 시도하는 것이 첫 단계입니다.

# iOS: Pods 정리 후 재설치
cd ios
rm -rf Pods Podfile.lock
bundle exec pod install
cd ..

# Android: Gradle 캐시/빌드 산출물 정리
cd android
./gradlew clean
cd ..

# Metro 캐시까지 초기화하고 재실행
npx react-native start --reset-cache

그래도 같은 에러가 반복되면, 에러 메시지에 등장하는 라이브러리 이름을 키로 그 라이브러리의 New Architecture 지원 상태(2단계)로 돌아가 확인합니다. 대부분의 빌드 막힘은 결국 특정 라이브러리 한두 개로 좁혀집니다.

④ JavaScript 엔진(Hermes) 관련이 의심될 때

성능이나 실행 관련 문제가 의심되면, 우선 현재 프로젝트가 Hermes를 제대로 쓰고 있는지부터 확인하는 편이 현실적입니다. 확인 코드는 간단합니다.

const isHermes = () => !!global.HermesInternal;

console.log("Hermes 사용 여부:", isHermes());

다만 이 값이 true라고 해서 항상 최적화된 상태라는 뜻은 아닙니다. 공식 문서도 release 빌드에서 실제 전후를 비교하도록 권장합니다. 즉 이 확인은 "출발점 점검"이지 결론이 아닙니다.

✅ 마이그레이션 체크리스트

여기까지 내용을 한 장으로 정리하면 아래와 같습니다. 그대로 복사해 프로젝트 이슈나 노션에 붙여 쓰셔도 됩니다.

[사전 파악]
- [ ] 현재 React Native(또는 Expo SDK) 버전 확인
- [ ] 네이티브 연결 라이브러리 목록 작성
- [ ] 커스텀 네이티브 모듈 유무 확인

[호환 확인]
- [ ] 각 라이브러리의 New Architecture 지원 여부 확인 (reactnative.directory)
- [ ] 미지원 라이브러리: 최신화 / 대체 / 보류 결정
- [ ] 커스텀 모듈: Codegen 전환 필요 여부 확인

[적용]
- [ ] 중간 버전(예: 0.81 / Expo SDK 54)에서 New Architecture 활성화
- [ ] iOS 빌드 확인 (pod install 포함)
- [ ] Android 빌드 확인 (gradlew clean 포함)
- [ ] Interop Layer로 도는 부분과, 실제로 손봐야 하는 부분 구분

[검증]
- [ ] 자주 쓰는 핵심 화면 QA
- [ ] 카메라/지도/결제/푸시 등 민감 기능 개별 확인
- [ ] 문제 없으면 0.82 이상 업그레이드 검토

[기록]
- [ ] 막혔던 지점과 해결 방법을 남겨 다음 업그레이드에 재사용

🤔 그래서, 지금 옮겨야 할까?

마지막으로 판단 기준을 정리하겠습니다. 상황에 따라 답이 다릅니다.

지금 옮기는 편이 좋은 경우

• 앞으로도 오래 유지할 앱이고, 라이브러리 대부분이 이미 New Architecture를 지원한다.
• 곧 RN 버전을 올릴 계획이 있어서, 어차피 한 번은 거쳐야 한다.
• 새 기능·성능 개선을 계속 따라가야 하는 서비스다.

조금 기다려도 되는 경우

• 핵심 라이브러리 중 아직 미지원이 있고, 대체가 마땅치 않다.
• 지금 당장 큰 기능 배포 일정이 걸려 있어, 리스크를 늘리기 어렵다.
• 커스텀 네이티브 모듈이 많아 Codegen 전환 공수가 큰데, 검증 시간이 부족하다.

지금은 하지 말아야 하는 경우

• 라이브러리 호환 확인(2단계) 없이, 일정에 쫓겨 버전부터 올리려는 상황.

결국 마이그레이션은 "최신 버전이니까 올린다"가 아니라, 내 프로젝트가 New Architecture에서 문제없이 도는지 순서대로 확인하는 과정입니다. 오늘 정리한 순서대로만 접근해도, 원인을 못 찾아 헤매는 시간은 확실히 줄어듭니다.

🫡 마무리

이번 글에서는 개념 대신 실제로 넘어갈 때의 순서와 막힘에 집중했습니다. New Architecture가 왜 필요했고 Bridge 구조에 어떤 한계가 있었는지가 궁금하다면, 개념을 먼저 정리한 「React Native 0.82부터 레거시 아키텍처를 못 쓰는 이유」 글(발행 후 URL 연결)을 함께 보시면 흐름이 더 잘 이어집니다.

다음 글에서는 커스텀 네이티브 모듈을 Codegen 기반으로 바꾸는 과정을, 아주 작은 예제 모듈 하나로 처음부터 따라가 보겠습니다.

읽어 주셔서 감사합니다 🙇

---

참고 자료

• React Native 공식 블로그: The New Architecture is here
• React Native 공식 블로그: React Native 0.82 - A New Era
• React Native 공식 문서: Fabric Renderer
• React Native 공식 문서: Using Hermes