dependencies와 peerDependencies의 차이, 배포 시 생기는 오류

프로젝트를 개발할 때, 로컬 환경에서는 정상적으로 실행되지만 배포 후에는 특정 패키지가 동작하지 않거나 peerDependencies 관련 경고가 발생하는 경우가 있다. 이 글에서는 dependencies와 peerDependencies의 차이를 이해하고, 올바르게 패키지를 관리하는 방법을 정리해보겠다.

---

🔎 dependencies와 peerDependencies의 차이

✅ dependencies란?

dependencies는 프로젝트에서 직접 사용하고 실행에 필수적인 패키지를 의미한다. npm install을 실행하면 dependencies에 있는 모든 패키지가 node_modules에 설치된다.

예제 (package.json)

{
  "dependencies": {
    "react": "^18.2.0",
    "axios": "^1.3.4"
  }
}

 

📌 특징:

• npm install 시 자동으로 설치됨.
• 패키지를 설치할 때, 하위 dependencies도 함께 설치됨.
• 빌드 및 실행에 반드시 필요한 패키지.

---

✅ peerDependencies란?

peerDependencies는 프로젝트에서 필요하지만, 직접 포함하지 않고 상위 프로젝트(루트 프로젝트)에서 설치해야 하는 패키지를 의미한다. 보통 플러그인이나 UI 라이브러리에서 많이 사용된다.

예제 (package.json)

{
  "peerDependencies": {
    "react": "^18.2.0",
    "three": "^0.168.0"
  }
}

 

📌 특징:

• npm install 시 자동으로 설치되지 않음. (경고만 출력됨)
• 프로젝트를 사용하는 사람이 직접 설치해야 함.
• 같은 패키지가 중복 설치되는 것을 방지함 (ex: react가 두 번 설치되는 문제 해결).

 

📌 예제: react-three/xr은 three를 peerDependencies로 설정하여 사용자의 프로젝트에 맞게 버전을 유지하도록 강제한다.

---

🎯 dependencies vs peerDependencies 비교

구분 dependencies peerDependencies

구분	dependencies	peerDependencies
설치 방식	npm install 시 자동 설치	자동 설치되지 않음 (경고만 출력)
누가 설치해야 하나?	패키지를 설치한 프로젝트	루트 프로젝트에서 직접 설치해야 함
사용 예시	axios, lodash	react, three, next.js (프레임워크 기반 라이브러리)

---

🔥 배포 시 peerDependencies 관련 오류 해결 방법

1️⃣ peerDependencies가 자동으로 설치되지 않음

✅ 원인

• npm install을 실행해도 peerDependencies는 설치되지 않음.
• 로컬에서는 기존 node_modules에 이미 설치된 패키지가 있어서 정상적으로 동작할 수 있음.
• 배포 환경에서는 node_modules을 새로 생성하면서 peerDependencies가 누락될 가능성이 있음.

🛠 해결 방법

1. peerDependencies에 있는 패키지를 명시적으로 dependencies에 추가

   npm install three
   

   그리고 package.json의 dependencies에 추가:

   "dependencies": {
     "three": "^0.168.0"
   }
   

2. 배포 환경에서도 peerDependencies를 자동으로 설치하도록 설정

   npm install --legacy-peer-deps
   

   또는 package.json에 postinstall 스크립트 추가:

   "scripts": {
     "postinstall": "npm install --legacy-peer-deps"
   }
   

---

2️⃣ peerDependencies 버전 충돌 해결

✅ 원인

• 루트 프로젝트의 dependencies에서 요구하는 패키지 버전이 peerDependencies에서 요구하는 버전과 다를 경우 충돌 발생 가능.

🛠 해결 방법

1. 루트 프로젝트의 dependencies에서 요구하는 버전을 peerDependencies에 맞추기

   npm install react@18 react-dom@18
   

2. overrides 또는 resolutions 설정으로 버전 강제 통일

   "overrides": {
     "three": "0.168.0"
   }
   

   (📌 resolutions는 yarn 전용 기능)

---

🔥 package.json의 패키지 관리 필드 정리

✅ devDependencies

• 개발 환경에서만 필요한 패키지 (빌드, 테스트 도구 등).
• 예: eslint, webpack, jest 등.
• npm install --save-dev 명령어로 추가 가능.

예제

{
  "devDependencies": {
    "eslint": "^8.40.0",
    "webpack": "^5.88.0"
  }
}

---

✅ optionalDependencies

• 선택적으로 설치할 수 있는 패키지.
• 설치 실패해도 오류가 발생하지 않음.

예제

{
  "optionalDependencies": {
    "fsevents": "^2.3.2"
  }
}

---

✅ 최종 정리

 

🎯 dependencies, peerDependencies, devDependencies 차이

구분	설치 대상	예시
dependencies	프로덕션 실행에 필요한 패키지	react, axios
peerDependencies	프로젝트가 사용하는 특정 패키지의 버전을 루트 프로젝트에 맞춤	three, react
devDependencies	개발 환경에서만 필요한 패키지	eslint, webpack

 

🎯 peerDependencies 오류 해결 방법

1. 배포 환경에서도 peerDependencies가 설치되도록 dependencies에 추가
2. 버전 충돌이 발생하면 overrides 또는 resolutions 사용
3. npm install --legacy-peer-deps로 peerDependencies 강제 설치

이제 배포 환경에서도 peerDependencies 문제가 발생하지 않고 원활하게 동작할 것이다! 🚀