[npm] package.json 옵션 정리 *main, module, exports, type, types

1. 전체 옵션 (축약  by Chat GPT) 

1. name: 프로젝트의 이름입니다.
2. version: 프로젝트의 현재 버전입니다.
3. description: 프로젝트에 대한 간단한 설명입니다.
4. keywords: 프로젝트를 설명하는 키워드 배열입니다.
5. homepage: 프로젝트 홈페이지의 URL입니다.
6. bugs: 버그를 보고할 수 있는 이슈 트래커의 URL이나 이메일 주소입니다.
7. license: 프로젝트 라이선스를 명시합니다.
8. people fields:
   • author: 프로젝트의 저자에 대한 정보입니다.
   • contributors: 프로젝트에 기여한 사람들의 리스트입니다.
9. funding: 프로젝트의 재정 지원 정보입니다.
10. files: npm에 포함될 파일들 또는 디렉토리들의 배열입니다.
11. main: 패키지가 로드될 때의 진입점 파일을 지정합니다.
12. browser: 클라이언트 측 JavaScript에 대한 대체 모듈을 지정합니다.
13. bin: 프로젝트가 제공하는 하나 이상의 실행 가능한 파일을 명시합니다.
14. man: UNIX 매뉴얼 페이지의 위치를 명시합니다.
15. directories: 프로젝트의 다양한 디렉토리를 지정합니다.
    • directories.bin: 실행 가능한 파일이 위치한 디렉토리입니다.
    • directories.man: 매뉴얼 페이지가 위치한 디렉토리입니다.
16. repository: 프로젝트의 소스 코드가 호스팅되는 저장소 정보입니다.
17. scripts: 프로젝트에서 사용할 수 있는 스크립트 명령어들을 정의합니다.
18. config: 스크립트에서 사용할 수 있는 프로젝트별 구성 옵션입니다.
19. dependencies: 프로젝트 실행 시 필요한 npm 패키지들의 목록입니다.
20. URLs as Dependencies: URL을 통해 지정된 의존성입니다.
21. Git URLs as Dependencies: Git URL을 통해 지정된 의존성입니다.
22. GitHub URLs: GitHub URL을 통해 지정된 의존성입니다.
23. Local Paths: 로컬 경로를 통해 지정된 의존성입니다.
24. devDependencies: 개발 시에만 필요한 npm 패키지들의 목록입니다.
25. peerDependencies: 호환되는 패키지의 버전을 명시합니다.
26. peerDependenciesMeta: peerDependencies에 대한 추가 메타데이터를 제공합니다.
27. bundleDependencies: 패키지와 함께 번들링되는 의존성 목록입니다.
28. optionalDependencies: 선택적 의존성을 명시합니다.
29. overrides: 의존성의 하위 의존성을 재정의합니다.
30. engines: 프로젝트가 호환되는 Node.js 엔진의 버전을 명시합니다.
31. os: 프로젝트가 지원하는 운영 체제를 명시합니다.
32. cpu: 프로젝트가 지원하는 CPU 아키텍처를 명시합니다.
33. private: true로 설정하면 npm에 공개되지 않습니다.
34. publishConfig: npm에 패키지를 공개할 때의 설정을 명시합니다.
35. workspaces: 다중 패키지 구조를 관리하는데 사용되는 작업 공간 목록입니다.
36. type: modue || commonJS 인지 모듈 결정
37. types: 타입스크립트 컴파일러나 코드 에디터에게 해당 패키지의 타입 정의 파일의 위치를 알려줌
38. exports : main 옵션과 더불어 패키지의 진입점을 설정할 수 있음 ( exports 에서 명시 하지 않는 경로는 접근 불가능)
39. module :  ES6 호환 환경에서 패키지를 사용할 때 진입 되는 경로 (yarn 2+)

2. 옵션 별 내용 

Description

This document is all you need to know about what's required in your package.json file. It must be actual JSON, not just a JavaScript object literal.

A lot of the behavior described in this document is affected by the config settings described in config.

• name 
  • package를 실행하기 위한 필수항목. 
  • name+version 옵션으로 유니크한 식별자 구성
  • 규칙: 214글자 이하, 점이나 밑줄 금지, 대문자 사용 금지, URL에 사용 불가능한 문자 포함 금지
  • 팁: 노트의 코어 모듈과 같은 이름 사용 x, "js""node"을 포함 x, npm info [이름] 을 통해 중복 체크

• version 
  • name과 더불어 필수항목
  • 버전은 node-semver가 인식할 수 있어야 함 (npm에 포함되어 있음) 
  • 1.2.1 과 같이 작성 됨. 각 도트 별 의미는 major.minor.patch 
  • 코드 수정사항에 대한 의미에 맞게 릴리즈 시 버전 업 시켜주면 됨

• homepage 
  • 프로젝트의 홈페이지 주소 The url to the project homepage.
  • eg) "homepage": "https://github.com/owner/project#readme"

• bugs
  • 프로젝트 이슈 트랙커의 주소나 이슈를 보고할 수 있는 이메일 주소

{
  "bugs": {
    "url": "https://github.com/owner/project/issues",
    "email": "project@hostname.com"
  }
}

• license
  • BSD-2-Clause나 MIT와 같은 일반적인 라이센스를 사용한다면 SPDX 라이센스 식별자를 사용
• people fields: author, contributors
  • 개인: author / 조직 : contributors로 지정
• files
  • 프로젝트에 포함시킬 파일들의 배열 
  • 패키지 최상위 폴더나 하위 폴더에 .npmignore 파일이 있으면 해당 파일에 기록된 파일 배열들은 패키지 배포시 제외 됨
  • cf) .npmignore가 없으면 .gitignore를 통해 자동으로 제외 파일들 설정 함
  • 항상 포함되는 파일들
    • package.json
    • README (및 여기에 해당되는 여러가지 변형파일들)
    • CHANGELOG (와 여기에 해당되는 변형 파일들)
    • LICENSE / LICENCE
  • 항상 제외 되는 파일들
    • .git
    • CVS
    • .svn
    • .hg
    • .lock-wscript
    • .wafpickle-N
    • *.swp
    • .DS_Store
    • ._*
    • npm-debug.log
• main 
  • 프로그램의 시작 포인트를 가리키는 모듈 ID
  • 패키지 이름이 foo이면 이 패키지를 설치한 사용자가 require("foo")를 호출하면 메인 모듈이 export한 객체를 반환하게 됨
  • 모듈 ID는 패키지 폴더의 최상위를 기준으로 한 상대 경로여야 함.
  • 보통 dist 라는 폴더 (distribute) 를 만들어서 해당 폴더 내의 index로 설정해둠 (dist는 배포 후 사용자들이 사용하게 될 것들을 모아둔 것)
• bin, man, directories 설명은 패스
• repository
  • 코드를 저장하는 저장소 지정
  • 해당 저장소가 깃헙이라면 npm docs 명령어로 이 저장소의 소유자 찾기 가능

"repository" :
 { "type" : "git"
 , "url" : "https://github.com/npm/npm.git"
 }

"repository" :
 { "type" : "svn"
 , "url" : "https://v8.googlecode.com/svn/trunk/"
 }

• scripts
  • 패키지의 라이프 사이클에서의 다양한 순간에 실행되는 스크립트 명령어 담아줌
  • 라이프 사이클 : prepare, prepublish, prepublishOnly, prepack, postpack, dependencies
  • key는 라이프 사이클 이벤트 (build, prepare, start , test, dev 등등)
  • value 는 실행 할 명령어
• config 
  • 패키지 스크립트에서 사용되는 설정 파라미터 지정 가능

{ 
	"name" : "foo", 
	"config" : { "port" : "8080" } 
}

• dependecies
  • 프로젝트 실행 시 필요한 패키지 정보 모음
  • 개발 모드에서만 사용되는 것들은 devDependecies에 정의 됨 (테스트 도구 같은) 
  • 버전 정보
    • version : version에 정확히 일치해야합니다.
    • >version: 지정된 version보다 더 커야합니다.
    • >=version
    • <version
    • <=version
    • ~version : 해당 버전에 대략적으로 일치해야합니다.
    • ^version : 해당 버전과 호환이되어야 합니다.
    • 1.2.x : 1.2.0, 1.2.1 등등, 1.3.0은 안됩니다.
    • http://... : URL 의존성 참고
    • * : 모든 버전와 매칭됩니다.
    • "" : (빈 문자열) *과 동일합니다.
    • version1 - version2 : >=version1 <=version2와 동일합니다.
    • range1 || range2 : range1 또는 range2중에 하나를 만족하면 통과합니다.
    • git... : Git URL 의존성 참고
    • tag : 태그되었거나 tag로 퍼블리쉬된 버전을 지정합니다.
    • path/path/path : 로컬 경로를 참고하기 바랍니다.

{ "dependencies" :
 { "foo" : "1.0.0 - 2.9999.9999"
 , "bar" : ">=1.0.2 <2.1.2"
 , "baz" : ">1.0.2 <=2.3.4"
 , "boo" : "2.0.1"
 , "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
 , "asd" : "http://asdf.com/asdf.tar.gz"
 , "til" : "~1.2"
 , "elf" : "~1.2.3"
 , "two" : "2.x"
 , "thr" : "3.3.x"
 , "lat" : "latest"
 , "dyl" : "file:../dyl"
 }
}

• devDependencies: 개발 시에만 필요한 npm 패키지들의 목록입니다.
• peerDependencies: 호환되는 패키지의 버전을 명시합니다.
• peerDependenciesMeta: peerDependencies에 대한 추가 메타데이터를 제공합니다.
• bundleDependencies: 패키지와 함께 번들링되는 의존성 목록입니다.
• optionalDependencies: 선택적 의존성을 명시합니다.
• engines
  • 호환되는 node의 버전을 지정 할 수 있음

{ "engines" : { "node" : ">=0.10.3 <0.12" } }

{ "engines" : { "npm" : "~1.0.20" } }

• os 
  • 모듈이 동작 할 수 있는 os 지정 (!를 사용해서 블랙리스트 지정도 가능)

"os" : [ "darwin", "linux", "!win32" ]

• cpu 옵션 또한 위와 같음
• private 
  • npm 에 배포 가능에 대한 설정
  • true인 상태에서 배포한다면 에러 일으킴

"private": true

• type
  • "type": "module": 이 설정은 패키지 내의 .js 파일들이 ECMAScript 모듈(ESM)로 처리되어야 함을 나타냄. ESM은 import와 export 문을 사용하여 모듈을 불러오고 내보내는 현대적인 자바스크립트 모듈 시스템
  • 파일의 확장자가 .mjs이거나 type 필드가 module일 경우 패키지는 ES Module를 사용하여 import나 import() 함수를 사용할 수 있음.
  • "type": "commonjs" 또는 "type" 필드가 생략된 경우: .js 파일들은 기본적으로 CommonJS(CJS) 모듈로 처리됨. CommonJS는 require()와 module.exports를 사용하는 Node.js의 전통적인 모듈 시스템
  • 파일 확장자가 .cjs이거나 type 필드가 commonjs일 경우(혹은 생략) import, import() 함수, require() 함수를 사용할 수 있음
• types
  • 타입스크립트(TypeScript)를 사용하는 프로젝트에 대해 중요한 역할
  • 타입스크립트 컴파일러나 코드 에디터에게 해당 패키지의 타입 정의 파일의 위치를 알려줌.
  • 타입스크립트가 해당 패키지를 사용할 때 필요한 타입 정보를 제공하여, 타입 체킹과 자동 완성 기능을 지원
  • 만약 당신의 패키지가 index.js라는 메인 파일을 가지고 있고, 이에 대한 타입 선언 파일이 index.d.ts라면, package.json에 다음과 같이 작성

{
  "name": "your-package",
  "main": "index.js",
  "types": "index.d.ts",
  // ... 다른 설정들
}

• exports 
  • main 필드와 exports 필드를 사용하면 패키지의 진입점을 설정할 수 있음.
  • node 버전 10 이하에서는 main 필드 사용. 11 이상부터는 main과 exports 옵션이 있다면 exports의 우선순위가 더 높음
  • exports 필드는 main 필드와 다르게 여러 개의 진입점을 설정할 수 있음
  • 단, exports 에서 명시 하지 않는 경로는 접근 불가능

{
  "exports": {
    ".": "./lib/index.js",
    "./lib": "./lib/index.js",
    "./feature": "./feature/index.js"
  }
}

위의 코드에서는 ./feature/utils.js가 exports 필드에 명시 되어있지 않기 때문에 import util from 'beomy-lib/feature/utils.js'가 불가능. 이러한 경우 다른 파일들과 동일하게 ./feature/utils.js를 exports 필드에 추가하거나 아래와 같이 작성하여 해결 할 수 있습니다.

{
  "name": "beomy-lib",
  "exports": {
    ".": "./lib/index.js",
    "./lib": "./lib/index.js",
    "./feature": "./feature/index.js",
    "./feature/*.js": "./feature/*.js"
  }
}

import BeomyLib from 'beomy-lib'
// Loads ./node_modules/beomy-lib/lib/index.js

import BeomyLib from 'beomy-lib/lib'
// Loads ./node_modules/beomy-lib/lib/index.js

import BeomyLib from 'beomy-lib/feature'
// Loads ./node_modules/beomy-lib/feature/index.js

import BeomyLib from 'beomy-lib/feature/utils.js'
// Loads ./node_modules/beomy-lib/feature/utils.js

• module
  • module 필드는 main 필드와 유사한 목적으로 사용 되는 필드입니다. ES6 호환 환경에서 패키지를 사용할 때 진입 되는 경로

{
  "module": "./sources/index.mjs"
}

 

참고사이트

https://docs.npmjs.com/about-packages-and-modules

About packages and modules | npm Docs

https://beomy.github.io/tech/etc/package-json/

[ETC] package.json 톺아보기

https://outofbedlam.gitbooks.io/npm-handbook/content/config/package-json.html

package.json · npm 핸드북