[React] npm install 시 의존성 충돌 오류 해결 방법

문제 상황

npm install 명령어를 실행했을 때 다음과 같은 에러가 발생했습니다.

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! While resolving: web@0.26.0
npm ERR! Found: react@18.3.1
npm ERR! Could not resolve dependency:
npm ERR! peer react@"0.14.0 || ^15.0.0 || ^16.0.0 || ^17.0.0" from react-masonry-component@6.3.0

에러 원인 분석

• 현재 프로젝트에서는 react@18.3.1을 사용하고 있음.
• 하지만 react-masonry-component@6.3.0은 react@0.14 ~ 17까지만 지원하고 있어 충돌이 발생.
• 이로 인해 npm이 의존성 트리를 해결하지 못하고 설치가 실패함.

해결 방법

1. --legacy-peer-deps 옵션 사용

가장 간단하게는 아래 명령어로 의존성 설치를 강행할 수 있습니다.

npm install --legacy-peer-deps

이 옵션은 peer dependency 충돌을 무시하고 설치를 진행합니다. 다만, 설치 이후 실행 시 호환성 문제가 생길 수 있으므로 기능 테스트는 꼭 필요합니다.

2. react-masonry-component 제거 또는 대체

react-masonry-component가 필수 요소가 아니라면 패키지를 제거하거나, React 18을 지원하는 대체 라이브러리로 교체하는 것이 바람직합니다.

예를 들어 다음과 같은 라이브러리들을 사용할 수 있습니다:

• masonry-layout
• react-masonry-css

3. React 버전을 낮추기

프로젝트 전체에서 React 18이 반드시 필요한 것이 아니라면, React 버전을 17로 낮추는 것도 하나의 방법입니다.

npm install react@17 react-dom@17

하지만 이 방식은 다른 라이브러리들과의 충돌 가능성이 높기 때문에 주의가 필요합니다.

결론

방법	설명	추천도
--legacy-peer-deps 사용	충돌 무시하고 설치	★★★★☆
라이브러리 교체	masonry 관련 라이브러리를 React 18 호환으로 대체	★★★★★
React 버전 다운그레이드	전체 호환성에 주의 필요	★★☆☆☆