React 19 환경에서 @toast-ui/react-editor 설치가 안 되는 문제

로컬에서는 npm install이 잘 됐는데 Vercel 배포 시 빌드 단계에서 터졌다.

에러 메시지

npm error code ERESOLVE
npm error ERESOLVE could not resolve
npm error While resolving: @toast-ui/react-editor@3.2.3
npm error Found: react@19.2.4

원인

@toast-ui/react-editor@3.2.3의 peer dependency가 react@^17.0.0 || ^18.0.0으로 명시돼 있다. React 19는 지원 범위 밖이라 npm이 설치를 거부한 것.

로컬에서는 되던 이유는 npm 버전이나 설정 차이 때문이었다. Vercel은 npm의 strict peer dependency 모드로 동작한다.

해결

프로젝트 루트에 .npmrc 파일을 만들고 한 줄 추가:

legacy-peer-deps=true

Vercel도 이 파일을 읽어서 빌드 시 자동 적용된다.

정리

의존성 충돌은 로컬 환경과 배포 환경이 다를 수 있다. 새 패키지 설치할 때 peer dependency 범위를 미리 확인하는 게 낫다. toast-ui가 React 19 대응 버전을 내놓지 않으면 나중에 에디터 교체가 필요할 것 같다.