[React] 리액트 설치 npm install 실패 해결법

📌 문제

npm ERR! ERESOLVE unable to resolve dependency tree

 

npm install 명령어 실행할 때 아래와 같은 오류나면서 설치 실패함

Initialized git repository. Installing template dependencies using Foe error

Error: Unable to resolve dependency tree

While resolving: my-app@0.1.0  
Found: react@19.0.0  
node_modules/react  

Peer dependency issue:  
- react@18.0.0 is required by @testing-library/react@13.4.8  
- Found: @testing-library/react@13.8.0 in node_modules/testing-library/react  

Could not resolve dependency conflict.

Suggestions:  
1. Fix the dependency conflict.  
2. Retry with `--force` or `--legacy-peer-deps` to accept an incorrect dependency resolution.

For a full report, see the logs:  
'C:\Users\YourUser\AppData\Local\npm-cache\logs\2025-01-01T13_00_00_666Z-resolve-report.txt'

A complete log of this run can be found in:  
'C:\Users\YourUser\AppData\Local\npm-cache\logs\2025-01-01T13_00_02_506Z-debug.log'

Failed commands:  
- `npm install`  
- `npm install --save @testing-library/jest-dom@5.14.1 @testing-library/react@13.8.0 @testing-library/user-event@13.2.1 web-vitals@2.1.0`

 

✅ 원인

의존성 충돌 문제

 

프로젝트에서는 react@19.0.0을 설치하려고 하는데 @testing-library/react와 호환되는 버전은 react@18.0.0 이라서 발생하는 문제이다. npm이 버전 충돌을 자동으로 해결할 수 없어서 설치가 안된 것이다.

 

✅ 해결법

호환 버전 확인

아래 명령어 쓰면 @testing-library/react의 호환되는 peerDependencies를 출력해준다. 

 npm info @testing-library/react peerDependencies

 

 

---

아니면 package.json 파일을 열어서 peerDependencies 부분을 확인해보면 호환되는 react 버전을 확인할 수 있다.

"peerDependencies": {
  "react": "^16.8.0 || ^17.0.0 || ^18.0.0"
}

 

호환되는 버전 설치

예를 들어 react@18.0.0 설치하려면 아래 명령어처럼 입력하면 된다. 

npm install react@18 react-dom@18

 

강제 설치나 --legacy로 설치

아니면 아래 명령어 두 개 중에 하나 선택해서 설치하면 된다. 

npm install --save --legacy-peer-deps

 

`--legacy`는 peerDependency가 맞지 않아도 일단 설치

npm install --force

 

`--force`

 

모든 의존성 문제를 무시하고 강제로 설치를 진행하는 명령어(사용주의)

package-lock.json과 실제 의존성 트리를 강제로 덮어쓰면서 맞지 않는 버전의 의존성 까지도 추가하거나 변경해버릴 수 있기 때문에 잘못된 의존성 구조가 만들어져서 나중에 프로젝트에 예상치 못한 의존성 버전이나 충돌이 포함될 수 있다.

의존성 문제를 빠르게 해결해야 할 때 사용해도 되지만 결과를 안정적으로 보장할 수는  없음. (최후의 수단)