[NodeJS] 공식문서와 함께하는 package.json에 대한 모든 것 1탄

우리가 노드를 사용할때 늘 보는 package.json이지만 취준생이나 주니어개발자들에게 package.json이 뭐에요? 라고 물어보면 당당하게 제대로 대답 할 수 있는 사람이 몇이나 될까??

강의에서도 보면 package.json에 대한 설명은 간단하게만 하고 넘어가거나 생략하는 경우가 대부분이다 그렇기 때문에 스스로 공부하고 찾아보고 알아봐야하는데 이러한 과정을 거치는 것이 얼마나 귀찮은 일인가...

얼마전 누군가에게 package.json과 package-lock.json이 뭐고 그 차이가 뭔지 물어본적이 있는데 개발자로 근무한지 1년되었음에도 이에 정확한 대답을 하지 못하여 나 자신에게 너무 충격을 받았다.

지금에서라도 package.json이 무엇인지 제대로 알고자 공식문서를 찾아보았다.

 

해당 글을 https://docs.npmjs.com/cli/v8/configuring-npm/package-json npm 공식문서를 읽으며 번역하여 기록해두기로 한다.

 

Description

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.

 

설명

이 문서는 당신은 package.json을 작성할 때 필요한 모든 것들을 알수 있다. 

package.json을 작성 할 때, JavaScript의 오브젝트 리터럴이 아니라 실제 JSON format이여야 한다.

이 문서에 설명된 많은 동작은 config에 설명된 구성 설정의 영향을 받는다.

 

Name

name

If you plan to publish your package, the most important things in your package.json are the name and version fields as they will be required. The name and version together form an identifier that is assumed to be completely unique. Changes to the package should come along with changes to the version. If you don't plan to publish your package, the name and version fields are optional.

The name is what your thing is called.

Some rules:

• The name must be less than or equal to 214 characters. This includes the scope for scoped packages.
• The names of scoped packages can begin with a dot or an underscore. This is not permitted without a scope.
• New packages must not have uppercase letters in the name.
• The name ends up being part of a URL, an argument on the command line, and a folder name. Therefore, the name can't contain any non-URL-safe characters.

Some tips:

• Don't use the same name as a core Node module.
• Don't put "js" or "node" in the name. It's assumed that it's js, since you're writing a package.json file, and you can specify the engine using the "engines" field. (See below.)
• The name will probably be passed as an argument to require(), so it should be something short, but also reasonably descriptive.
• You may want to check the npm registry to see if there's something by that name already, before you get too attached to it. https://www.npmjs.com/

A name can be optionally prefixed by a scope, e.g. @myorg/mypackage. See scope for more detail.

 

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

name과 version을 통해 각 패키지의 고유성을 판별하게 된다. 따라서 패키지의 내용을 변경하려면 version을 변경해야만 한다.

단, 패키지를 게시하지 않으려는 경우는 name과 version의 항목은 선택사항이다.

 

name은 어떻게 불릴지에 대한 것이다.

 

몇가지 규칙: 

• 214자 이하여야 하며 범위가 지정된 패키지(scope package)의 범위(scope)가 포함된다.
• 범위가 지정된 패키지의 이름은 점( . )이나 밑줄( _ )로 시작할 수 있지만, 범위 없이는 허용되지 않는다.
• 새 패키지는 이름에 대문자가 없어야 한다. 
• name은 URL의 일부, Command Line의 인수 및 폴더명이 된다. 따라서 이름에는 URL에 안전하지 않은 문자가 포함되어서는 안된다.

몇가지 조언:

• Node의 코어 모듈(core module)과 같은 이름을 사용하지 않는다.
• name에 "node" 또는 "js"를 넣지 않는다. package.json파일을 작성하는 시점에서 이미 JavaScript라는 것을 알수 있고 "engines" 항목에서 엔진을 지정할수 있으므로 js라고 가정한다.(아래 참고)
• name은 require()에 대한 인수로 전달되는 것으로 짧지만 합리적으로 설명해야한다. 
• npm 레지스트리를 확인하여 해당 이름의 항목이 이미 있는지 확인할수 있다.

name에는 선택적으로 범위가 접두사로 붙을 수 있는데, @myorg/mypageage의 형태가 될 수 있다. 자세한 내용은 npm-scope를 참고한다.

 

Version

version

If you plan to publish your package, the most important things in your package.json are the name and version fields as they will be required. The name and version together form an identifier that is assumed to be completely unique. Changes to the package should come along with changes to the version. If you don't plan to publish your package, the name and version fields are optional.

Version must be parseable by node-semver, which is bundled with npm as a dependency. (npm install semver to use it yourself.)

 

버전(version)

pakeage.json에서 가장 중요한 항목은 "name"과 "version"이라고 앞서 다뤘었다. 필수로 입력되어야 하며 해당 항목이 누락되면 패키지를 설치 할 수 없다.

name과 version을 통해 각 패키지의 고유성을 판별하게 되기때문에 패키지의 내용을 변경하려면 version을 변경해야만 한다.

version은 반드시 npm의 디펜던시에 포함된 node-semver로 parsing 가능해야 한다. (직접 확인하고싶다면, npm install semver로 설치해보길 바란다.)

 

Description

description

Put a description in it. It's a string. This helps people discover your package, as it's listed in npm search.

 

description

설명을 문자열로 기술한다. npm search로 검샌된 리스트에 표시되기 때문에 사람들이 당신이 만든 패키지를 찾아 내고 이해하는데 도움이 된다.

 

Keywords

keywords

Put keywords in it. It's an array of strings. This helps people discover your package as it's listed in npm search.

 

keywords

키워드를 문자열 배열로 설명한다. npm search로 검색된 리스트에 표시되기 때문에 사람들이 당신이 만든 패키지를 찾고 이해하는데 도움이 된다.

 

Homepage

homepage

The url to the project homepage.

Example:

 

"homepage": "https://github.com/owner/project#readme"

 

homepage

프로젝트 홈페이지가 있는 경우 이 항목에 입력한다.

주의 : 이것은 URL 항목과는 다르다. 만약 URL을 설정한다면 그것은 외부에 설치된 패키지 소스로 리디렉션 되고, 예상치 못한 움직임을 유발할수 있다.

예시:

 

"homepage": "https://github.com/owner/project#readme"

 

Bugs

bugs

The url to your project's issue tracker and / or the email address to which issues should be reported. These are helpful for people who encounter issues with your package.

It should look like this:

 

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

You can specify either one or both values. If you want to provide only a url, you can specify the value for "bugs" as a simple string instead of an object.

If a url is provided, it will be used by the npm bugs command.

 

bugs

프로젝트의 이슈 크래킹을 볼 수 있는 URL과 이슈를 알릴 email 주소를 입력한다. 이는 패키지에 문제가 있는 사람들에게 도움을 주기 위함이다.

이와 같이 표기 되어야 한다:

 

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

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

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

 

 

License

license

You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you're placing on it.

If you're using a common license such as BSD-2-Clause or MIT, add a current SPDX license identifier for the license you're using, like this:

 

{
	"license" : "BSD-3-Clause"
}

 

You can check the full list of SPDX license IDs. Ideally you should pick one that is OSI approved.

If your package is licensed under multiple common licenses, use an SPDX license expression syntax version 2.0 string, like this:

 

 

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

If you are using a license that hasn't been assigned an SPDX identifier, or if you are using a custom license, use a string value like this one:

 

 

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

Then include a file named <filename> at the top level of the package.

Some old packages used license objects or a "licenses" property containing an array of license objects:

 

 

// Not valid metadata
{
    "license" : {
        "type" : "ISC",
        "url" : "https://opensource.org/licenses/ISC"
    }
}

 

// Not valid metadata
{
    "licenses" : [
        {
            "type": "MIT",
            "url": "https://www.opensource.org/licenses/mit-license.php"
        },
        {
            "type": "Apache-2.0",
            "url": "https://opensource.org/licenses/apache2.0.php"
        }
    ]
}

Those styles are now deprecated. Instead, use SPDX expressions, like this:

 

 

{
	"license": "ISC"
}

 

 

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

Finally, if you do not wish to grant others the right to use a private or unpublished package under any terms:

 

 

{
	"license": "UNLICENSED"
}

Consider also setting "private": true to prevent accidental publication.

 

license

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

 

"license": "BSD-3-Clause"

 

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

만약 패키지가 여러 개의 라이센스 아래에 있다면, 아래와 같이 SPDX license expression syntax version 2.0 string 을 사용해서 표현한다.

 

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

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

 

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

 

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

 

오래된 패키지 중 일부는 licenses 라는 속성으로 라이센스들의 목록을 가지고 있었지만, 이 방식은 현재 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 로 설정함으로써 미연에 퍼블리싱하게 되는 것을 막아줄 수도 있다.