NPM에서 Yarn으로 마이그레이션을 진행하고 리눅스 서버에 배포를 진행하다 peer-dependency 오류가 발생했습니다. 처음에는 "로컬에서는 잘 되는데 왜 서버에서만 문제가 생기지?"라는 의문이 들었습니다. 이전에 rollup 라이브러리가 os에 의해 정상적으로 install 되지 않았던 경험이 있었기에 단순 os 차이인 줄 알았지만 문제의 핵심은 peer dependency의 충족 여부였습니다.
Some peer dependencies are incorrectly met; run yarn explain peer-requirements for details
이런 로그와 오류가 발생했습니다.. 이 상황을 해결하기 위해 yarn explain peer-requirements란 무엇이고 어떨 때 쓰는건지 알아보겠습니다.
peer dependency란?
위 명령어를 이해하기 위해서는 peer dependency가 무엇인지 알아야합니다. peer dependency란
어떤 패키지가 "나는 특정 패키지의 특정 버전이 필요해!"라고 요구하는 의존성입니다. 하지만 이 패키지는 직접 설치되지 않고, 프로젝트(혹은 상위 패키지)에서 직접 설치해줘야 합니다.
프로젝트에서 설치한 라이브러리 들이 어떤 peer dependency를 가지고 있는지 조회할 수 있는 명령어가 yarn explain peer-requirements입니다.
이 명령어를 실행하면, 충족되지 않은 peer dependency 목록과 각각의 문제에 대한 해시(hash)가 출력됩니다.
특정 문제의 상세 설명을 보고 싶다면, 아래처럼 해시를 지정해 실행할 수 있습니다.
yarn explain peer-requirements <hash>예시 결과:
위 리스트에서 x가 되어이 있는 해시가 peer dependency 충족 되지 않은 라이브러리입니다.
해결 방법
저는 이 문제를 .yarnrc.yml의 packageExtension 설정을 통해
가짜 종속성을 주입하여 문제를 해결했습니다.
packageExtensions란?
Yarn의 .yarnrc.yml 파일에서 제공하는 packageExtensions는, 특정 패키지의 의존성 정의를 확장하거나 보완할 수 있게 해주는 기능입니다.
즉, 서드파티 패키지가 잘못된(혹은 누락된) peer dependency를 선언했을 때, 직접적으로 해당 의존성을 추가해 Yarn이 올바르게 dependency tree를 구성하도록 도와줍니다.
실제 적용 예시
- 문제 진단
yarn explain peer-requirements로 어떤 패키지에서 어떤 peer dependency가 누락됐는지 확인합니다.
우리가 사용하는 vue-query가 내부적으로 React 생태계의 react-query를 의존하는데, react가 설치되어 있지 않아 종속성 문제가 발생하는 것입니다.
하지만 우리는 vue를 사용하고 react를 사용하기 때문에 라이브러리를 설치 할 필요가 없습니다. 오히려 설치하면 불필요한 라이브러리이기 때문에 번들 사이즈만 증가시키는 문제가 발생합니다.
이를 해결하기 위해 .yarnrc.yml에 가짜 의존성을 주입하여 문제를 해결하는 것입니다.
enableStrictSsl: false
npmRegistry: ''
//...
packageExtensions:
"react-query@3.39.3":
peerDependencies:
"react": "*"packageExtendions 설정에 종속성 주입이 필요한 라이브러리를 기입하고 peerDependencies 설정을 통해 가짜 종속성이 필요한 라이브러리를 기입하여 가짜 종속성을 생성할 수 있습니다.
단 이 문제는 해당 모듈을 import하거나 사용할 일이 없는 경우에만 안전하게 쓸 수 있습니다. 만약 코드에서 react를 직접 사용한다면, 진짜로 패키지를 설치해야 합니다.
정리
오늘은 .yarnrc.yml을 사용하여 가짜 종속성을 만들고 이를 통해 peer-dependency 오류를 수정하는 방법을 알아보았습니다. 항상 무슨 내용인지 잘 몰랐는데 빌드를 여러 환경에서 적용하고 시도하다 보니 오류를 수정하게 되어 번들링과 종속성에 대해 좀 더 자세하게 알아보아야 할 것 같습니다..!
수정해야 할 내용이나 피드백이 있다면 언제든지 부탁드리겠습니다. 글 읽어주셔서 감사합니다!
