yarn Workspace에서 공통 패키지 수정 시 HMR이 동작하지 않는 문제 디버깅
진단하기
yarn workspace를 사용하여 서비스들과 공통 코드를 나누어 관리하는 모노레포 환경에서 문제가 발생했어요.
문제 상황:
- 공통 코드 워크스페이스 패키지들을 수정한 후,
dev server를 껐다 켜줘야만 반영되는 현상 - 개발 중
HMR(Hot Module Replacement)이 동작하지 않아 생산성이 크게 저하됨 - 작업 중간에 yarn이 패키지를 resolve하는 과정에서 peer dependency를 찾지 못하는 에러가 발생
이 문제로 인해 공통 패키지를 수정할 때마다 개발 서버를 재시작해야 했고, 이는 개발 속도를 크게 느리게 만들었어요.
재현하기
재현 조건
- yarn workspace 기반 모노레포 환경
- 여러 서비스가 공통 패키지를 의존하는 구조
- 공통 패키지 코드 수정
- dev server 실행
발생하는 문제
- 공통 패키지 수정 사항이 실시간으로 반영되지 않음
- yarn의 패키지 resolution 과정에서 peer dependency 탐색 실패
HMR이 트리거되지 않아 수동으로 서버 재시작 필요
수정하기
yarn PnP(Plug'n'Play) API로 전환
기존 node_modules 방식에서 yarn PnP API를 사용하도록 변경했어요. yarn PnP는 node_modules 폴더를 생성하지 않고, .pnp.cjs 파일을 통해 패키지 의존성을 관리하는 방식이에요.
// .yarnrc.yml
nodeLinker: pnp; // node-modules에서 pnp로 변경주요 변경 사항:
- 패키지 해상도 최적화: PnP는 패키지를 설치할 때 디스크에 복사하는 대신, .pnp.cjs 파일에 매핑 정보만 저장해요
- 의존성 그래프 명확화: peer dependency 해상도가 더 명확하고 빠르게 동작해요
HMR지원: 워크스페이스 패키지 변경 시 즉시 감지되어HMR이 정상 동작해요
이렇게 yarn PnP로 전환한 결과, 공통 패키지를 수정해도 dev server를 재시작할 필요 없이 즉시 반영되게 되었어요!
재발방지하기
모노레포 환경에서 yarn PnP 활용
yarn workspace를 사용하는 모노레포 환경에서는 node_modules 방식보다 yarn PnP가 더 효율적일 수 있어요. 특히 여러 패키지가 서로를 참조하는 구조에서는 PnP의 명확한 의존성 해상도가 많은 문제를 예방할 수 있어요.
개발 생산성을 위한 HMR 최적화
공통 패키지를 수정할 때마다 서버를 재시작해야 한다면 개발 속도가 극도로 느려져요. 모노레포를 구성할 때는 처음부터 HMR이 잘 동작하는지 확인하고, 동작하지 않는다면 빠르게 해결해야 해요. yarn PnP, PNPM, Turborepo 같은 최신 도구들은 이런 문제를 더 잘 해결해요.
Peer Dependency 문제 조기 발견
yarn이 peer dependency를 찾지 못하는 에러는 패키지 구조나 설정에 문제가 있다는 신호예요. 이런 경고를 무시하지 말고, 근본 원인을 해결하는 것이 중요해요. yarn PnP는 이런 문제를 더 명확하게 드러내고 해결하기 쉽게 만들어줘요.
새로운 도구에 대한 열린 자세
node_modules 방식이 익숙하다고 해서 계속 고집할 필요는 없어요. yarn PnP처럼 새로운 접근 방식이 문제를 더 잘 해결한다면, 적극적으로 도입을 검토해야 해요. 초기에는 러닝 커브가 있을 수 있지만, 장기적으로는 개발 경험을 크게 개선할 수 있어요.