본문으로 건너뛰기

package.json – 환경 및 배포 설정 필드 정리

Summary​

package.json의 환경 및 배포 설정 필드는 패키지가 어떤 환경에서 실행되어야 하는지, 어떤 조건에서 배포되어야 하는지를 정의한다. 이를 통해 플랫폼 호환성 오류를 사전에 방지하고, 공개 여부나 퍼블리싱 전략을 명시할 수 있다.

Details​

engines​

지원하는 Node.js 또는 npm 버전을 명시한다. 해당 조건을 충족하지 않으면 경고 또는 오류가 발생한다.

"engines": {
  "node": ">=16.0.0",
  "npm": ">=8.0.0"
}
정보

기본적으로는 경고만 출력되며, engineStrict를 설정하거나 .npmrc에서 강제해야 설치 오류로 처리된다.

engineStrict​

설치 시 engines 조건을 강제할지를 설정한다. npm v7 이상에서는 무시되며, .npmrc 파일에서 설정하는 것이 일반적이다.

"engineStrict": true
주의

이 필드는 현재 deprecated 상태이며, 대신 .npmrc에 engine-strict=true를 사용하는 것이 권장된다.

os​

허용된 운영체제를 배열로 명시한다. 지정되지 않은 운영체제에서는 설치가 차단된다.

"os": ["darwin", "linux"]
  • darwin: macOS
  • win32: Windows
  • linux: Linux

cpu​

지원하는 CPU 아키텍처를 배열로 명시한다.

"cpu": ["x64", "arm64"]
  • x64: 인텔/AMD 64비트
  • arm64: M1, M2, ARM 기반

private​

해당 필드가 true일 경우 npm publish 명령어가 차단된다. 실수로 퍼블릭 레지스트리에 배포되는 것을 방지한다.

"private": true
팁

모노레포 루트나 내부용 패키지에서 반드시 사용하는 것이 좋다.

publishConfig​

배포 관련 설정을 세부 조정할 수 있다. 레지스트리, 접근 범위, 태그 등을 지정한다.

"publishConfig": {
  "registry": "https://registry.npmjs.org/",
  "access": "public",
  "tag": "next"
}

registry​

퍼블리싱 시 사용할 npm 레지스트리 주소를 지정한다.

access​

  • "public": 퍼블릭 공개 (default)
  • "restricted": 조직 내부 npm 레지스트리에만 공개

tag​

배포 시 기본으로 지정할 태그. "latest" 대신 "next" 또는 "beta" 등으로 설정 가능.

Reference​

author note: Related note in this repo

link: External reference