[React Native] 버전 3중 추돌 사건 해결 과정(react-native-reanimated, react-native-screens)

📖들어가며..

React Native앱을 구현하면서 Drawer 네비게이션을 열때 구글맵이 언마운트 마운트가 되면서 렉이 생기고, 앱이 다운되는 문제가 있었다.

개발 환경에서 애뮬레이터의 성능이 좋지 않아서 그런가? 했지만 해당 문제를 계속 놔둘 수 없어서 문제 원인을 찾던 도중 버전 문제이지 않을까? 해서 버전을 수정하고자 했다.

하지만 이때부터 버전 3중 추돌 사건이 발생했다.

문제의 상황들과 해결 과정을 기록하고자 한다.

 

 

---

🤔버전을 수정하려면 node-modules 폴더와 package.lock.json을 삭제해야겠지?

성능문제 관련해서 버전 문제일 수 있다는 생각에 버전을 수정하고자 했다.

그래서 node-modules 폴더와 package.lock.json을 삭제했는데 

 

여기서 문제가 바로 발생한다.

그냥 버전 수정하고node-modules 폴더와 package.lock.json 삭제한 뒤에 npm install 하면 되겠지?

했다.

 

근데 아니었다.

갑자기 버전 충돌 문제가 생기면서 설치가 안된다.

C:\Users\User\Documents\GitHub\my-map-react-native>npm i
npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: AwesomeProject@0.0.1
npm error Found: react-native-worklets@0.5.2
npm error node_modules/react-native-worklets
npm error   react-native-worklets@"^0.5.2" from the root project
npm error
npm error Could not resolve dependency:
npm error peer react-native-worklets@">=0.7.0" from react-native-reanimated@4.2.1
npm error node_modules/react-native-reanimated
npm error   react-native-reanimated@"^4.1.3" from the root project
npm error   peer react-native-reanimated@">= 2.0.0" from @react-navigation/drawer@7.7.10
npm error   node_modules/@react-navigation/drawer
npm error     @react-navigation/drawer@"^7.5.2" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.
npm error
npm error
npm error For a full report see:
npm error C:\Users\User\AppData\Local\npm-cache\_logs\2026-01-06T11_30_48_736Z-eresolve-report.txt
npm error A complete log of this run can be found in: C:\Users\User\AppData\Local\npm-cache\_logs\2026-01-06T11_30_48_736Z-debug-0.log

 

위 에러를 요약하면

 

• react-native-reanimated@4.2.1
• 👉 react-native-worklets 0.7.0 이상을 요구
• 하지만 프로젝트에는 0.5.2가 설치돼 있음

 

근데 사실 이전에 해당 버전으로 정상 작동했었는데 에러가 발생한 것 부터 의문이었다.

React를 사용하면서 버전관련해 충돌이 거의 난 적이 없어서 그런지 당황스러웠다.

 

일단 위에서 나오는 라이브러리들은 모두 사용하고 있는 라이브러리이기 때문에 삭제는 안된다.

ChatGPT같은 AI에서는 버전을 내리거나 npm install --legacy-peer-deps 를 사용하라고 한다.

 

먼저  npm install --legacy-peer-deps 방법은 사용하면 안된다.

런타임에서 무슨 에러가 날지 모르고, 실제로 해봤는데 npm run android 실행을 했을 때 에러가 발생한다.(버전이 안맞는다고)

 

그럼 이제 버전을 내려야하는데 도대체 몇 버전으로 내려야할까?

ChatGPT가 말하는 대로 버전을 수정하는 것이 과연 신뢰할 수 있는 방법일까?

 

 

🤔공식문서를 찾아보자

https://docs.swmansion.com/react-native-reanimated/docs/guides/compatibility/

Compatibility table | React Native Reanimated

해당 라이브러리의 공식문서에 버전에 관련해서 상세하게 작성되어있었다.

4.2.x 버전이었으니까 

worklets는 0.7.0 으로 바꾸면 된다.

이렇게 신뢰할 수 있는 자료가 있어서 다행히 버전 수정을 진행할 수 있었다.

 

그럼 이제 위 자료대로 버전을 수정하고 npm install로 설치를 진행했다.

 

그 결과

다행히 설치가 잘 되었다.

 

🤔버전 2번째 충돌

설치 이후 바로 npm run android로 실행해보았다.

그런데 아래와 같은 에러가 발생했다.

Execution failed for task
:react-native-reanimated:assertMinimalReactNativeVersionTask

[Reanimated] Your installed version of React Native (0.79.4)
is not compatible with installed version of Reanimated (4.2.1)

 

👉 React Native 버전과 Reanimated 버전이 호환되지 않음

 

이제는 갑자기 내 React Native 버전과 충돌이 난다고 한다..

위 자료를 자세히 보니 아래와 같은 문제가 있었다.

 

• react-native-reanimated@4.2.1은
• React Native 최신 버전만 지원
• 하지만 프로젝트의 RN 버전은 그보다 낮음
• -> Reanimated는 Android 빌드 시 Gradle Task에서 RN 최소 버전을 강제 체크하기 때문에
  호환되지 않으면 빌드 자체를 중단한다.

근데 나는 RN 버전 0.79.4를 사용하기로 처음에 결정했었다.

0.8이상으로 바꾸면 어떤 문제가 발생할 지 모르고,

나는 앱에 react-native-map 라이브러리를 사용하고 있는데 이게 0.80 버전에서 이슈가 있었고,

또한 drawer 네비게이션에서도 이슈가 있어서 0.79.4 버전을 택했다.

 

그래서 react-native-reanimated의 버전을 4.1.x 버전, worklets의 버전도 0.6.x로 낮추기로 결정했다.

 

 

🤔버전 3번째 충돌

그럼 이제 아래처럼 버전을 세팅해서 다시 설치 후 npm run android를 실행했다.

    "react-native-reanimated": "4.1.3",
    "react-native-worklets": "0.6.1",
    "react": "19.0.0",
    "react-native": "0.79.4",

 

하지만 또 에러가 발생했다.

Error: Unknown prop type for "environment": "undefined"
Task :react-native-screens:generateCodegenSchemaFromJavaScript FAILED

👉 React Native Codegen과 Screens 불일치

 

React Native (core + codegen)
        ↑
react-native-screens
        ↑
@react-navigation/*

 

• react-native-screens 최신 버전은 새로운 prop (environment)를 사용
• 하지만 현재 RN의 codegen은 이 타입을 모름

 

즉 이건 JS 에러가 아니라 Android Native 코드 생성 단계에서 터진 에러다.

 

이것도 자료를 찾아보니 버전 문제였다.

https://www.npmjs.com/package/react-native-screens

나는 4.18버전을 사용하고 있었다.

공식문서의 버전을 보면 문제 없는 거 아닌가? 했는데 4.14버전으로 바꾸니 해결되었다..

 

 

---

🤔왜 계속 이런 일이 생겼나?

나는 처음에 RN을 설치하고 라이브러리를 추가로 계속해서 설치하는 과정으로 진행했다.

그러다 보니 버전에 대해서 신경쓰지 않고 개발이 진행되었고, 

node-modules, package.lock.json을 삭제하고나니 문제가 터진 것이다.

버전을 누가 올리는지 확인해보니 네비게이션 관련 패키지였다.

 

정리하자면

1. npm은 최신 버전을 최대한 설치하려고 함
2. React Native 네이티브 라이브러리들은
   • RN 버전에 극도로 민감
   • 하위 호환이 잘 깨짐
3. @react-navigation/* 패키지들이
   • 내부적으로 reanimated, screens, worklets를 끌어올림
4. 한 개만 맞춰도 다른 게 다시 깨지는 구조

즉, 의존성 지뢰밭이 되어버렸다.

 

🚨추가로 발생한 버전 충돌

추가로 react-error-boundary 라이브러리를 설치할 때 최신버전으로 하면 충돌이 난다.

그래서나는 지금 현재 버전 기준으로 6.0.0으로 설치했다.

 

또 react-native-fast-image 라이브러리를 사용하려고 했는데 이것도 react 19버전에서 충돌이 있는 이슈가 있었다.

그래서 나는 해당 라이브러리를 fork하여 관리하고있는 라이브러리를 설치해 사용했다.

https://www.npmjs.com/package/@d11/react-native-fast-image

 

 

 

 

---

✍️이를 통해 배운 점

❌ 하면 안 되는 것

• React Native 프로젝트에서
  • 네이티브 라이브러리 무작정 최신 설치
• “JS니까 괜찮겠지” 마인드

✅ 반드시 지켜야 할 원칙

1. React Native 버전이 기준
2. Reanimated / Screens / Worklets는
   • 항상 RN 호환표 확인
3. Navigation 라이브러리는
   • 내부 네이티브 의존성까지 고려
4. 문제 생기면
   • resolutions 또는 overrides로 강제 고정
5. Android 빌드 에러는
   • JS 문제가 아니라 Native 생태계 문제일 확률이 높다