peerDependencies와 peerDependenciesMeta 가이드

peerDependencies와 peerDependenciesMeta 가이드

package.json을 다루다 보면 dependencies와 devDependencies는 익숙하지만, peerDependencies는 헷갈릴 때가 많다.
특히 라이브러리나 플러그인을 만들 때 중요한 역할을 하지만, 잘못 사용하면 버전 충돌이나 예상치 못한 에러를 초래할 수 있다.

또한, peerDependenciesMeta를 활용하면 특정 패키지를 선택적으로(optional) 의존하도록 설정할 수 있다.
이 글에서는 peerDependencies와 peerDependenciesMeta의 개념과 올바른 사용법을 정리해 보려고 한다.

1. peerDependencies란?

peerDependencies는 패키지가 호환되는 다른 패키지의 특정 버전을 요구할 때 사용된다.
즉, 내 패키지가 어떤 특정 라이브러리와 함께 동작할 것을 전제로 할 때, 해당 라이브러리의 버전 범위를 peerDependencies에 명시하는 것이다.

{
    "peerDependencies": {
        "react": "^18.0.0"
    }
}

위처럼 설정하면, npm이나 yarn은 패키지를 설치할 때 react@18.x.x가 설치되어 있어야 하며, 그렇지 않다면 다음과 같은 경고 메시지를 노출한다.

npm WARN my-package@1.0.0 requires a peer of react@^18.0.0 but none is installed. You must install peer dependencies yourself.

이러한 점은 일반 dependencies와 차이가 존재한다.

2. dependencies vs peerDependencies vs devDependencies

종류	설명
dependencies	패키지가 정상적으로 동작하는 데 필요한 필수 패키지
devDependencies	개발 및 빌드 과정에서만 필요한 패키지 (예: 테스트 도구)
peerDependencies	패키지를 사용하는 프로젝트에서 설치해야 하는 패키지

예제 비교

(1) dependencies 사용

{
    "dependencies": {
        "react": "^18.0.0"
    }
}

이 경우, 패키지를 설치하면 react도 자동으로 설치된다.

(2) peerDependencies 사용

{
    "peerDependencies": {
        "react": "^18.0.0"
    }
}

이 경우, react가 프로젝트에 없으면 경고만 발생하고 자동 설치되지 않는다. 사용자가 직접 설치해야 한다.

3. 언제 peerDependencies를 사용해야 할까?

1. 라이브러리에서 특정 패키지와 함께 동작해야 할 때

예를 들어, react 기반의 UI 컴포넌트 라이브러리를 만든다고 가정해보자.

{
    "peerDependencies": {
        "react": "^18.0.0",
        "react-dom": "^18.0.0"
    }
}

위와 같이 설정하면 라이브러리를 사용하는 프로젝트에서 react@18이 반드시 설치되어 있어야 한다.

2. 플러그인 또는 확장 기능을 만들 때

예를 들어, eslint의 플러그인을 만들 경우:

{
    "peerDependencies": {
        "eslint": "^8.0.0"
    }
}

이렇게 하면 eslint가 프로젝트에 필수로 설치되어 있어야 하며, 특정 버전 범위와의 호환성을 유지할 수 있다.

4. peerDependenciesMeta란?

peerDependenciesMeta는 peerDependencies의 추가적인 메타데이터를 제공하는 속성이다. 주로 특정 peerDependencies를 선택적(optional)으로 만들 때 사용한다.

{
    "peerDependencies": {
        "webpack": "^5.0.0"
    },
    "peerDependenciesMeta": {
        "webpack": {
            "optional": true
        }
    }
}

위와 같이 설정하면 webpack이 없더라도 경고가 발생하지 않는다. 즉, 사용자가 필요하면 설치하고, 그렇지 않으면 무시할 수 있다.

5. peerDependenciesMeta 실전 예제

1. Webpack 플러그인 개발할 때

{
    "peerDependencies": {
        "webpack": "^5.0.0"
    },
    "peerDependenciesMeta": {
        "webpack": {
            "optional": true
        }
    }
}

webpack이 없으면 플러그인 기능이 일부 비활성화될 수 있지만, 필수는 아니므로 경고 없이 사용할 수 있다.

2. ESLint 플러그인 개발할 때

{
    "peerDependencies": {
        "eslint": "^8.0.0"
    },
    "peerDependenciesMeta": {
        "eslint": {
            "optional": true
        }
    }
}

eslint가 설치되지 않았더라도 경고가 표시되지 않는다. 사용자가 eslint를 설치하면 추가 기능을 사용할 수 있다.

6. peerDependenciesMeta vs optionalDependencies

peerDependenciesMeta와 optionalDependencies는 완전히 다른 개념이다.

속성	설명
peerDependenciesMeta	peerDependencies의 일부 패키지를 선택적으로 만들 때 사용
optionalDependencies	프로젝트가 특정 패키지를 자동으로 설치하지만, 설치에 실패해도 오류 없이 넘어감

{
    "optionalDependencies": {
        "webpack": "^5.0.0"
    }
}

이 설정은 webpack이 자동으로 설치되지만, 설치에 실패해도 오류 없이 계속 진행된다.

• peerDependenciesMeta는 경고를 제거하는 역할
• optionalDependencies는 자동 설치 + 실패해도 무시하는 역할

7. 결론

• peerDependencies는 호환성을 유지해야 하는 필수 패키지를 선언하는 용도로 사용된다.
• peerDependenciesMeta를 활용하면 특정 패키지를 선택적으로 만들 수 있다.
• optionalDependencies와 혼동하지 않도록 주의하며, 사용하자.