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

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

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

Documentation for the npm registry, website, and command-line interface

docs.npmjs.com

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

[ETC] package.json 톺아보기

package.json에는 프로젝트에 대한 설명, 패키지, 실행 스크립트 등의 정보를 담는 매니페이스(Manifest) 파일입니다. 이번 포스트에서는 package.json에서 설정할 수 있는 필드 값들을 하나씩 살펴보도록

beomy.github.io

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

package.json · npm 핸드북

outofbedlam.gitbooks.io

저작자표시 변경금지

'오픈소스' 카테고리의 다른 글

@radix-ui 훑어보기 - accordion (0)	2024.03.24
npm에 배포해보기 (1)	2024.01.09

Weeeeey

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

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

2. 옵션 별 내용

Description

'오픈소스' 카테고리의 다른 글

티스토리툴바

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

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

2. 옵션 별 내용

Description

'오픈소스' 카테고리의 다른 글

관련글

티스토리툴바