개발👩‍💻/프론트엔드

Package.json 살펴보기

gigibean 2022. 7. 4. 21:23

728x90

Package.json

name

package.json 에서 가장 중요한 항목은 name과 version이다. 필수로 입력되어야 하며 없다면 패키지를 설치하게 할 수 없다.

name과 version을 통해 각 패키지의 고유성을 판별하게 되고, 그렇기 때문에 내용이 변경된다면 version을 바꾸어 주어야만 한다.

규칙

점이나 밑줄로 시작할 수 없고
대문자를 포함해서는 안된다.
URL의 일부분임으로, 커맨드라인의 인수이자 폴더명이다. 따라서 모든 URL-safe하지 않은 name은 거부된다.

조언

name에 node또는 js를 넣지 않는다. package.json을 쓰고 있는 시점에서 이미 JS라는 것을 알 수 있고, engines항목에서 실행기반을 지정할 수 있다.
name은 JS 파일 내에서 require()함수의 인수로 사용되므로 짧고 알기 쉬운 것으로 짓는 것이 좋다.
설정 전에 같은 이름이 이미 있는지 확인하려면 npm를 참조한다.
name은 scope에 의해 접두어가 추가될 수 있는데 예를 들면 @org/package 와 같은 형태가 될 수 있다. Mono Repo and Tools - NPM Scop의 사용

version

packge.json에서 가장 중요한 항목은 name과 version
version은 node-semver로 parsing가능 해야한다.
npm3로 오면 서 flat한 디펜던시 관리를 위해 semver를 기준으로한 버전관리가 중요해졌다.

homepage

프로젝트의 홈페이지가 있을 경우

description

keywords

bugs

프로젝트의 이슈와 버그 트래킹을 볼 수 있는 url과 이슈를 알릴 email 주소를 입력한다. 이 항목은 패키지 사용자가 문제에 직면했을 때 도움을 주기 위함이다.

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

url이나 email 중 하나만 적용할 수도 있다.

license

패키지 사용자들이 당신이 만든 패키지를 사용하기 위해 어떻게 권한을 얻었는지 또 어떤 금기 사항이 있는지 알게 하기 위해 라이센스를 사용
가장 간단한 항법은 BSD-3-Clause나 MIT 같은 일반적인 라이센스의 표준 SPDX ID를 아래와 같이 지정하는 것이다.

"license": "BSD-3-Clause"

https://spdx.org/licenses/ 에서 SPDX 라이센스 아이디 전체 리스트를 볼 수 있다. OSI 에서 승인한 것들 중 하나를 사용 하는 것이 이상적이다.

만약 패키지가 여러개의 아리센스 아래 있다면 http://npmjs.com/package/spdx 를 사용해서 표현한다.

"license" : "(ISC OR GPL-3.0)"

만약 SPDX 식별자로 할당되지 않은 라이센스를 사용한다면 아래와 같이 SPDX 표현을 따라 해당 라이센스를 지정해준다.

"license" : "SEE LICENSE IN <filename>"

에 명시된 파일은 패키지의 톱레벨에 포함시킨다.

오래된 패키지 중 일부는 라이센스라는 속성으로 라이센스 목록을 가지고 있지만 현재 이방식은 deprecated되었다.

// 아래의 방식은 더이상 사용하지 않는다.
"license" : {
    "type" : "ISC",
    "url" : "http://opensource.org/licenses/ISC"
}


// 아래의 방식은 더이상 사용하지 않는다.
"licenses" : [{
    "type": "MIT",
    "url": "http://www.opensource.org/licenses/mit-license.php"
},
{
    "type": "Apache-2.0",
    "url": "http://opensource.org/licenses/apache2.0.php"
}]

대신 아래와 같이 SPDX 표현을 사용해야한다.

"license": "ISC"

"license": "(MIT OR Apache-2.0)"

마지막으로 비공개로 사용하거나 어떤 조건에서도 패키지를 퍼블리싱하지 않을 경우 아래와 같이 명시해준다.

"license": "UNLICENSED"

이런 경우 ”private” : true로 설정함으로써 미연에 퍼블리싱하게 되는 것을 막아줄 수도 있다.

people fields: author, contributors

“author": {
    "name" : "Barney Rubble",
    "email" : "b@rubble.com",
    "url" : "http://barnyrubble.tumblr.com/"
}

"author": "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"

npm은 또한 “maintainers”라는 필드에 당신의 npm 사용자 정보를 설정한다.

files

프로젝트에 포함된 파일의 배열이다
폴더 이름을 지정하면 폴더 안에 파일도 포함된다.

또한 ‘.npmignore’ 이라는 파일을 패키지의 루트 혹은 하위 폴더에 둘수 있는데 이 파일에 기록된 파일들은 ‘files’ 의 배열로 지정되어 있었다고 해도 대상에서 제외된다. ‘.npmignore’ 파일은 ‘.gitignore’ 파일과 유사하다고 보면된다. .npmignore 파일이 없다면 .gitignore 파일에 규칙을 따른다.

다음의 파일들을 설정에 관계없이 항상 포함된다.

package.json
README
CHANGELOG
LICENSE or LICENCE

반대로 일부 파일들은 항상 무시된다.

.git
cvs
.svn
.hg
.lock-wscript
wafpickle-N
*.swp
.DS_Store
._*
npm-debug.log

main

당신의 프로그램의 시작점이 되는 모듈의 ID이다 즉, ‘foo’라는 패키지가 있다면 이패키지를 사용자가 설치한뒤 require(“foo”)를 실행했을 때 ‘main’으로 지정한 모듈의 exports 객체가 반환된다.

bin

script

scripts | npm Docs
more info: npm-pack | npm Docs npm-ci | npm Docs

scripts | npm Docs

How npm handles the "scripts" field

docs.npmjs.com

npm-ci | npm Docs

Clean install a project

docs.npmjs.com

package.json파일 내 script속성은 여러 임의의 스크립트와 더불어 내장 스크립트와 해당 스트립트들들의 지정된 리이프 사이클 이벤트들
이 스크립트들은 npm run-script <stage> 혹은 npm run <stage> 로 실행될 수 있다.
스크립트 이름과 매칭되는 pre 혹은 post 명령어들도 순서에 맞게 실행된다. (prescript -> script -> postscript) 종속성의 script들도npm explore -- npm run ` 명령어로 실행될 수 있다.

Pre & Post Scripts

pre 혹은 post 스크립트를 만들고 싶다면, 해당 스크립트 이름과 일치하는 스크립트를 생성하여 pre, post 를 그 앞에 붙여주면 된다.

{
  "scripts": {
    "precompress": "{{ executes BEFORE the `compress` script }}",
    "compress": "{{ run command to compress files }}",
    "postcompress": "{{ executes AFTER `compress` script }}"
  }
}

Life Cycle Scripts

특정 상황에서만 스크립트가 실행되는 특별한 라이프 사이클을 가지는 스크립트 들이 몇개 있다.
이러한 스크립트는 pre<event> post<event> <event> 에도 발생한다.

* `prepare`, `prepublish`, `prepublishOnly`, `prepack`, `postpack`

prepare (since npm@4.0.0)

이 명령어는 npm publish 혹은 npm pack 로 패키지가 pack되기 전에 실행된다.

Runs BEFORE the package is packed
Runs BEFORE the package is published
Runs on local npm install
without any arguments
Run AFTER prepublish
, but BEFORE prepublishOnly
주의: 만약 prepare 스크립트를 가지고 있는 패키지를 깃에서 install한다면, 해당 패키지가 pack 혹은 install 되기 전, 해당 패키지의 dependencies와 devDependencies가 install되고난 후, prepare 스크립트가 실행된다.
해당 스크립트들은 background에서 실행된다. 막얀 output을 보고 싶다면 —foreground-scripts와 함께 실행하자

prepublish (DEPRECATED)

npm publish 될때 실행되지 않는다. npm cli 혹은 npm install 실행될 때 실행된다.

prepublishOnly

패키지가 prepared되거나 packed 되기 전에 실행된다. 오직 npm publish에서만 실행된다.

prepack

tarball이 패킹되기 전에 실행됩니다(npm pack, npm publish”및 git 종속성을 설치할 때).
참고: “npm run pack”은 “npm pack”과 다릅니다. “npm run pack”은 임의의 사용자 정의 스크립트 이름이며, 여기서 “npm pack”은 CLI 정의 명령입니다.

postpack

타르볼이 생성된 후 최종 대상으로 이동되기 전에 실행됩니다(전혀 있는 경우 게시에서 타르볼을 로컬에 저장하지 않음).

라이프 사이클 작업 순서

npm cache add
- prepare
npm ci
- preinstall
- install
- postinstall
- prepublish
- preprepare
- prepare
- postprepare
  이들은 모두 node_modules에 모듈을 실제로 설치한 후 순서대로 실행되며, 그 사이에 내부 작업이 발생하지 않습니다.

npm diff
- prepare
npm install
These also run when you run npm install -g <pkg-name>
- preinstall
- install
- postinstall
- prepublish
- preprepare
- prepare
- postprepare
  - npm pack
  - prepack
- prepare
- postpack
  - npm publish
  - prepublishOnly
- prepack
- prepare
- postpack
- publish
- postpublish
  prepare will not run during —dry-run
npm rebuild
- preinstall
- install
- postinstall
- prepare
  prepare is only run if the current directory is a symlink (e.g. with linked packages)
npm restart
If there is a restart script defined, these events are run, otherwise stop and start are both run if present, including their pre and post iterations)
- prerestart
- restart
- postrestart
npm run
- pre
- post
npm start
- prestart
- start
- poststart
  If there is a server.js file in the root of your package, then npm will default the start command to node server.js. prestart and poststart will still run in this case.
  - npm stop
  - prestop
- stop
- poststop
npm test
- pretest
- test
- posttest
npm version
- preversion
- version
- postversion

uninstall

npm v6에는 수명 주기 스크립트 제거가 있었지만 npm v7에는 없다. 패키지 제거는 다양한 이유로 발생할 수 있으며 현재 스크립트에 유용할 만큼 충분한 컨텍스트를 제공할 수 있는 명확한 방법이 없다.

패키지 제거 이유는 다음과 같습니다.
사용자가 이 패키지를 직접 제거했습니다.
사용자가 종속 패키지를 제거했으므로 이 종속성이 제거됩니다.
사용자가 종속 패키지를 제거했지만 다른 패키지도 이 버전에 종속됨
이 버전은 다른 버전과 중복으로 병합되었습니다.
등.
필요한 컨텍스트가 없기 때문에 제거 수명 주기 스크립트가 구현되지 않고 작동하지 않습니다.

config

https://docs.npmjs.com/misc/config

engines

동작 가능한 node 버전을 지정할 수 있다.

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

주의 할 점은 사용자가 engine-strict config flag를 설정하지 않으면 이 필드는 단지 조언용으로만 사용된다.

os

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

화이트 리스트 방식대신 블랙리스트 방식으로 지정할 수도 있다. 단순히 OS 앞에 “!” 를 붙이것만으로도 사용가능하다.

"os" : ["!win32"]

운영체제의 문자열은 process.platform에 의해 결정된다.

cpu

코드가 특정한 cpu 아카텍처에서만 동작한다면 명시해줄 수 있다.
화이트 블랙 리스트 모두 가능

"cpu" : ["x64", "ia32"]

"cpu" : ["!arm", "!mips"]

호스트 아키텍쳐는 process.arch 에 의해 결정된다.

preferGlobal

패키지가 클로벌 설치(-g)를 수행해야만 한다면 이값을 true로 해서 local 에서 설치시에 경고 메시지를 제공할 수 있다. 로컬 설치를 완전히 막지는 못하지만 경고문을 제공함으로써 다르게 동작하는 혼란을 피하는데 도움이 된다.

private

만약 ”private" : true로 설정해주면 publish명령을 거부하게된다.

publishConfig

publish 할 때 사용되는 설정
tag 와 registry, access를 다둘 때 편리하다.
이것들을 설정해서 패키지가 lastest로 태그되거나, public registry에 publish 되지 않도록 또 scoped module 을 기본값을로 private로 해주는 것등 쉽게 설정해줄 수 있다.

참고)
NodeJS 모두 알지만 모두 모르는 package.json | 감성 프로그래밍

[NodeJS] 모두 알지만 모두 모르는 package.json

이 글은 npm 의 https://docs.npmjs.com/files/package.json 을 번역한 글이며, 의역이 풍성하게 있습니다. 또 필요한 부분에는 이해를 돕기 위한 설명을 역자주 형태로 좀더 추가했습니다. node.js 컨퍼런스에

programmingsummaries.tistory.com

scripts | npm Docs

How npm handles the "scripts" field

docs.npmjs.com

https://docs.npmjs.com/misc/config

https://docs.npmjs.com/misc/config/

docs.npmjs.com

저작자표시 비영리