package.json 간단히 알아보기

NodeJS package.json

이 글에서는 package.json 파일에 작성되어 있는 것에 대해 간단히 알아보도록 하겠습니다.

더 많은 정보는 npm-config 를 참고바랍니다.

package.json

package.json 에서 가장 중요한 항목은 "name" 과 "version" 입니다.

이 항목들은 필수로 입력되어야 하며 이 항목들이 누락되면 여러분의 패키지는 설치할 수 없습니다.

name

name 과 version 을 통해서 각 패키지의 고유성을 판별하게 되고 패키지의 내용을 변경하려면 version 을 변경해야 합니다.

serveral rule

• name 은 반드시 214자 보다 짧아야 하고, 이는 scoped package 의 scope 를 포함합니다.
• name 은 점(.)이나 밑줄(_)로 시작할 수 없습니다.
• name 은 대문자를 포함해서는 안됩니다.
• name 은 URL의 일부분이자, 커맨드라인의 인수이고 폴더명입니다. 따라서 모든 URL-safe 하지 않은 name은 거부됩니다.

• Node 의 코어 모듈과 같은 이름을 사용하지 않습니다.
• name 에 "node" 또는 "js" 를 넣지 않습니다. package.json 을 쓰고 있는 시점에서 이미 JavaScript 라는 것을 알 수 있기 때문입니다.
• name 은 JavaScript 파일 내에서 require() 함수의 인수로 사용되므로 짧고 알고 쉬운 것으로 작명하는 것이 좋습니다.
• 설정 전에 같은 이름이 이미 있는지 확인하려면 npm registry 를 참조하도록 합니다.

version

version 은 반드시 npm의 디펜던시에 포함된 node-semver 로 pasing 가능해야 합니다. (직접 사용하려면 npm install sember 로 설치한다.)

version number 와 range 에 대한 상세한 정보는 semver 항목을 참고하도록 합니다.

description

설명을 문자열로 기술합니다.

npm search 로 검색된 리스트에 표시되기 때문에 사용자들이 당신이 만든 패키지를 찾아내고 이해하는 데 도움을 줄 수 있습니다.

keywords

키워드를 문자열 배열로 설명합니다.

키워드 역시 npm search 로 검색된 리스트에 표시되기 때문에 사용자들이 당신이 만든 패키지를 찾아내고 이해하는 데 도움을 줄 수 있습니다.

homepage

프로젝트 홈페이지가 있을 경우 이 항목에 입력할 수 있습니다.

이것은 "url" 항목과는 다르기 때문에 만약 "url" 을 설정하면 그것은 외부에 설치된 패키지 소스로 리디렉션 되고, 예상치 못한 움직임을 유발할 수 있으니 주위를 요합니다.

bugs

프로젝트의 이슈와 트래킹을 볼 수 있는 url과 이슈를 알릴 email 주소를 입력할 수 있습니다.

이 항목들은 패키지 사용자가 문제에 직면했을 때 도움을 주기 위함입니다.

package

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

url 이니 email 중 하나만 적용할 수 있고, url 만 지정하면 객체가 아니라 단순히 문자열을 "bugs" 항목에 지정할 수도 있습니다.

url 을 지정하는 경우에는 npm bugs 명령을 사용할 수 있습니다.

license

패키지 사용자들이 여러분이 만든 패키지를 사용하기 위해 어떻게 권한을 얻는지, 또는 어떤 금기 사항이 있는지 알게 하기 위해 라이센스를 명시해야 합니다.

가장 간단한 방법은 BSD-3-Clause 나 MIT 같은 일반적인 라이센스 표준인 SPDX ID 를 아래와 같이 지정하는 것입니다.

package

"license": "BSD-3-Clause"

https://spdx.org/licenses/ 에서 SPDX 라이센스 아이디 전체 리스트를 볼 수 있습니다.

OSI 에서 승인한 것들 중 하나를 사용하는 것이 이상적입니다.

SPDX 표현은 아래와 같이 사용해야 한다.

package

"license": "ISC"

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

people fields : author, contributors

"author" 는 한 사람만을 지정하고, "contributors" 는 여러 사람을 배열로 지정합니다.

각 사람은 아래와 같이 필수적으로 name 을 포함하고 선택적으로 email 과 url 값을 갖습니다.

package

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

또는 하나의 String 으로 아래와 같이 입력하면 npm 이 이를 파싱하게 된다.

package

"author": "Barney Rubble  (http://barnyrubble.tumblr.com/)"

files

"files" 항목은 프로젝트에 포함된 파일의 배열입니다.

폴더 이름을 지정하면 폴더 안의 파일도 포함되게 됩니다.(단, 다른 설정에 의해 해당 파일들이 무시되지 않는 경우)

또한, ".npmignore" 라는 파일을 패키지의 루트 혹은 하위 폴더에 둘 수 있는데, 이 파일에 기록된 파일들은 "files" 의 배열로 지정되어 있었다고 해도 대상에서 제외됩니다.

".npmignore" 파일은 ".gitignore" 파일과 유사하다고 보면 됩니다.

다음의 파일들은 설정에 관계없이 항상 포함됩니다.

• package.json
• README
• CHANGELOG
• LICENSE 또는 LICENCE

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

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

main

"main" 항목은 당신의 프로그램의 시작점이 되는 모듈의 ID입니다.

즉, 'foo' 라는 패키지가 있다면, 이 패키지를 사용자가 설치한 뒤, require("foo") 를 실행했을 때 "main" 으로 지정한 모듈의 exports 객체가 반환됩니다.

모듈 ID는 패키지 루트에 상대적인 경로를 지정해야 합니다.

대부분의 모듈에 있어서 메인 스크립트를 갖는 것은 유용하지만 종종 그렇지 않을 수도 있습니다.

repository

소스 코드가 관리되는 저장소 위치를 지정합니다.

소스 코드에 참여하고자 하는 사람들에게 도움이 될 수 있습니다.

만약 git 저장소가 github 라면 npm docs 명령으로 찾을 수 있습니다.

package

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

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

URL 은 특별한 조작없이 VCS 프로그램에서 바로 다뤄질 수 있도록 오픈되어 있어야 합니다.

컴퓨터를 위한 부분이므로, 프로젝트 홈페이지 URL을 명시해서는 안됩니다.

config

"config" 객체는 패키지의 버전에 관계없이 패키지 스크립트에서 사용될 수 있는 설정 정보입니다.

예를 들어, 패키지에 다음과 같은 값이 설정되어 있다고 한다면 :

package

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

"start" 명령을 실행할 때 npm_package_config_port 를 참조할 수 있게 됩니다.

다음의 명령으로 사용자가 이를 덮어 쓸 수 있습니다.

Command Line Interface

$ npm config set foo:port 8001

자세한 내용은 npm-config 및 npm-scripts 를 참조하도록 합니다.

dependecies

의존성을 규정하는 것은 패키지의 이름과 해당 패키지의 버전 범위를 지정한 객체를 통해 이루어집니다.

버전 범위는 하나 혹은 여러 개의 공백으로 분리된 설명자 문자열입니다.

의존성은 tarball 이나 git URL 로도 지정될 수 있습니다.

테스트 관련 모듈이나 트랜스 파일러 관련 모듈을 dependencies 객체에 추가하면 안됩니다.

운영이 아닌 개발단계에서만 필요한 의존성 모듈들은 devDependencies 에 설치해야 합니다.

semver 를 참고하면 버전 범위를 지정하는 방법에 대해 알수 있습니다.

• version : 명시한 version 과 일치해야 한다.
• >version : 명시한 version 보다 높아야 한다.
• >=version , <version, <=version
• ~version : 명시한 version 과 근사한 버전
• ^version : 명시한 version 과 호환되는 것
• * : 모든 버전을 말한다.
• "" : * 와 같다
• version1 - version2 : >=version1 <= version2 과 같음을 의미한다.
• range1 || range2 : range1 또는 range2

package

"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

패키지 모듈을 이용하는 사람이라면, 패키지 테스트 및 문서 작성에 사용되는 외부 프레임워크는 아마도 다운로드를 원하지 않을 것입니다.

이러한 경우 devDependencises 객체에 디펜던시를 추가하는 것이 좋은 방법입니다.

CoffieScript 와 같이 JavaScript 로 변환하는 플랫폼 특유의 전단계가 있을 때, devDenpendencies 가 필요할 것이다.

package

"name": "ethopia-waza",
"description": "a delightfully fruity coffee varietal",
"version": "1.2.3",
"devDependencies": {
    "coffee-script": "~1.6.3"
},
"scripts": {
    "prepublish": "coffee -o lib/ -c src/waza.coffee"
},
"main": "lib/waza.js"

prepubish 스크립트는 사용자들이 JavaScript 로 변환하지 않고도 사용할 수 있도록 퍼블리싱을 하기전에 실행될 것입니다.

Related Info

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

Jaehee's WebClub