[React] 릴리즈 후보(RC) 버전 사용 시 의존성 충돌 (ERESOLVE unable to resolve dependency tree)

[React] React 베타/RC 버전 설치 시 발생하는 의존성 충돌 해결하기(ERESOLVE unable to resolve dependency tree)

 

당시 신규 프로젝트를 시작하여 리액트 19버전을 설치하게 되었다.

리액트 19는 2024년 4월 25일에 공개되어 12월 5일에 안정화 버전이 출시되었는데, 당시에는 아직 안정화 버전이 출시되기 전이라 RC(릴리즈 버전)을 설치하게 되었다.

"dependencies": {
    "react": "19.0.0-rc-66855b96-20241106",
    "react-dom": "19.0.0-rc-66855b96-20241106",
},

 

릴리즈 후보 버전은 처음 설치해봐서 package.json 에 이러한 형태로 설치된 것을 보고 어리둥절했다.

사수한테 "이거 왜 이런 거예요?;" 하고 물어봤는데, 충돌나서 그렇다고 해결 방법을 정리한 노션 문서를 공유해주었다.

왜 리액트가 이런 형태로 설치된 것이며, 왜 이러한 충돌이 일어난 것인지 궁금해서 자세히 찾아보게 되었다.

 

 

🚨 Error : ERESOLVE unable to resolve dependency tree

릴리즈 버전 사용 시 발생한 문제 상황

세부적인 스타일링에 시간을 단축하기 위해 UI 라이브러리로 `mui(material-ui)` 를 사용하기로 했다.

그러나 mui 를 설치하던 도중 `ERESOLVE unable to resolve dependency tree` 라는 에러가 발생했다.

(예시)
npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: my-app@0.1.0
npm error Found: react@19.0.0-rc-69d4b800-20241021
npm error node_modules/react
npm error   react@"19.0.0-rc-69d4b800-20241021" from the root project

 

에러 메시지를 살펴보면 리액트 관련해서 의존성 트리에 문제가 생겼음을 알 수 있다.

 

 

의존성 충돌이란?

이와 같이 `npm i` 명령어 실행 시 발생하는 에러 메시지는 주로 의존성 충돌과 관련이 있다.

이런 에러가 발생하는 이유는 설치하려는 패키지의 의존성이 다른 패키지의 의존성과 충돌할 때 발생한다. 

 

예를 들어, 패키지 A는 react 18 버전을 사용하고 있고 패키지 B는 17버전 또는 19버전을 사용하고 있다고 하자.

이 경우 두 패키지의 경우 다른 버전의 react 를 요구하게 되는데, 이 때 npm 이 어떤 버전의 react 를 설치할 지 결정하지 못해 의존성 충돌을 발생시킨다.

 

npm 7 이상부터는 peer dependency 에 명시된 버전 범위와 실제 설치된 버전이 일치하지 않을 경우 이러한 오류를 발생시킨다.

 

 

의존성 충돌 해결 방법

1. 안정화 버전 사용하기

가장 권장되는 방법으로 릴리즈 버전 대신 안정적인 버전을 사용하는 것이다.

 

릴리즈 버전은 출시 직전의 마지막 테스트 버전으로 최종 안정성을 위해 추가 테스트가 필요한 상태이다.

검증이 이루어지지 않아 예기치 못한 버그가 발생할 수 있기 때문이다.

RC 버전은 알파 테스트와 베타 테스트(최초 출시)를 거쳐 사용자에게 최종적으로 검증받는 단계로 큰 버그가 없다면 정식 안정 버전으로 출시가 된다.

 

안정화 버전 확인하는 방법은 아래와 같다.

npm list react

 

여러 패키지가 서로 다른 버전의 리액트를 의존하고 있을 경우 다음과 같이 트리 구조의 형태로 출력된다.

library-x 가 내부의 의존성 패키지인 dependency-y 를 통해 리액트 17.0.2 버전을 요구하고 있는 경우이다.

my-app@0.1.0 C:\projects\my-app
├── react@18.2.0
└─┬ library-x@1.0.0
   └─┬ dependency-y@2.3.4
      └── react@17.0.2

 

이 때 설치된 리액트 버전이 라이브러리에서 요구하는 버전보다 낮은 경우 의존성 충돌 문제가 발생할 수 있는 것이다.

 

 

2. --legacy-peer-deps 플래그 사용

안정화 버전을 사용하는 것이 가장 베스트지만 릴리즈 버전을 계속 사용해야 한다면 설치 시 `--degacy-peer-deps` 옵션을 붙여서 사용하면 된다.

npm install --legacy-peer-deps

 

이 경우 peer dependency 검사를 건너 뛰어 의존성 충돌 오류를 무시할 수 있다.

--legacy-pper-deps 는 npm 7 방식이 아닌 npm 6 방식처럼 동작하여 의존성 충돌을 무시하는 방법이다.

 

하지만 이 방법도 향후 문제를 발생시킬 수 있기 때문에 안정화 버전을 사용하는 것이 더 좋다.

 

 

3. --force 옵션

`--force` 옵션을 사용하면 의존성 충돌이 일어나도 패키지들을 강제로 설치할 수 있지만 이 옵션은 권장되지 않는 방식이다.

npm install --force

 

 

4. 다른 패키지 매니저 사용

npm 대신 yarn 같은 패키지 매니저는 peer dependency 충돌에 대해 다르게 처리할 수 있으므로 다른 패키지 매니저를 사용하는 방법이 있다고 한다.

 

하지만 나의 경우에는 yarn 을 사용함에도 불구하고 위와 같은 에러가 발생했으므로 역시 가장 좋은 방법은 안정화 버전을 사용하는 방법이다.

 

 

 

마치며

최신 업데이트 기능을 사용하기 위해 19 버전의 RC 버전을 설치했으나 다른 라이브러리와 의존성 충돌이 발생했고, 이를 해결하기 위해 여러 가지 방법을 알아보았다.

 

가장 좋은 방법은 안정화된 버전을 사용하는 것이지만 꼭 RC 버전을 사용해야겠거나 업데이트된 기능을 사용해보고 싶다면 --legacy-peer-deps 옵션을 사용하여 의존성 충돌을 우회하는 방법을 선택할 수 있다.

 

나의 경우에는 일정이 빠듯하여 빠르게 결과물을 내야했으므로 `--legacy-peer-deps` 옵션을 사용하여 임시적으로 패키지들을 설치했다. 하지만 이것은 근본적인 해결책이 아니므로 예상치 못한 런타임 문제가 발생할 수 있기 때문에 되도록이면 정식 버전을 사용하는 것이 유지보수에도 좋다.