npm이 Peer Dependencies 기능을 도입해 플러그인 패키지가 호스트 패키지의 특정 버전과 호환성을 명시적으로 선언하도록 개선

Context

npm의 기본 의존성 관리 모델은 서브 디펜던시를 자동으로 격리하여 버전 충돌을 방지하지만, 플러그인 패턴에서는 한계가 드러난다. 플러그인은 호스트 패키지와 함께 사용되도록 설계되었으나, 호스트 패키지를 직접 의존성으로 명시하면 불필요한 복사본이 생기고, 명시하지 않으면 호환되지 않는 호스트 버전과 함께 설치될 수 있다. 예를 들어 winston-mail 0.2.3이 winston 0.5.x를 의존성으로 선언하고 앱 개발자가 winston 0.6.2를 설치하면, 두 개의 winston 복사본이 공존하면서 API 불일치로 인한 미묘한 실패가 발생한다.

Technical Solution

• Peer Dependencies를 package.json에 새로운 필드로 추가: 플러그인이 호스트 패키지의 호환 버전을 "peerDependencies" 해시로 명시
• npm 1.2.0 이상에서 peer dependency 검증 자동화: 설치 시 플러그인의 peerDependencies가 현재 설치된 호스트 패키지 버전과 일치하는지 확인
• 버전 충돌 감지 및 오류 보고: jitsu 0.11.6 설치 시 두 Flatiron 관련 패키지가 conflicting versions(0.1.9 vs 0.3.0)를 요구할 때 npm이 명시적 오류 반환
• npm 1, 2, 7에서 peerDependencies 자동 설치: 상위 의존성 트리에 명시되지 않으면 자동으로 설치
• npm 3~6에서 peerDependencies 경고 메커니즘: 누락 시 경고만 표시하고 설치하지 않음
• Semantic Versioning 기반 호환성 범위 설정: 플러그인 작성자가 메이저 버전 변경만으로 호스트 호환성이 깨진다고 가정하고 "~1.0" 또는 "1.x" 형식으로 명시

Key Takeaway

Plug-in 아키텍처에서 호스트와의 호환성을 패키지 매니저 수준에서 선언적으로 표현하면, 설치 시점에 버전 불일치를 자동으로 감지하여 런타임 실패를 사전에 방지할 수 있다. Peer dependency 범위를 느슨하게 설정하되 실제 테스트된 최소 버전을 명시하는 것이 에코시스템 전체의 의존성 충돌을 줄인다.