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

앞선 1탄에서는 아주 간단한 몇가지들을 다뤄보았다.

몇가지는 현재 실무에서도 사용하는 아주 흔한것들이지만 또 몇가지는 이런게 있었어? 라고 생각할만큼 생소한 내용도 있었다. 

 

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

 

people fields: author, contributors

people fields: author, contributors

The "author" is one person. "contributors" is an array of people. A "person" is an object with a "name" field and optionally "url" and "email", like this:

 

 

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

Or you can shorten that all into a single string, and npm will parse it for you:

 

 

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

Both email and url are optional either way.

npm also sets a top-level "maintainers" field with your npm user info.

 

 

작성자 영역: 작성자, 기여자

"저자"는 한 사람이다.  "기여자"는 사람들의 배열이다. "사람"은 다음과 같이 "이름"필드와 선택적으로 "url" 및 "email"이 있는 개체이다.

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

또는 이 모든 것을 단일 문자열로 줄일 수 있으며 npm이 이를 구문 분석한다.

 

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

 이메일과 URL은 선택사항이다.

npm은 또한 사용자 정보 최상위 "관리자" 필드를 설정한다.

 

 

funding

funding

You can specify an object containing a URL that provides up-to-date information about ways to help fund development of your package, or a string URL, or an array of these:

 

 

{
    "funding": {
        "type" : "individual",
        "url" : "http://example.com/donate"
    },

    "funding": {
        "type" : "patreon",
        "url" : "https://www.patreon.com/my-account"
    },

    "funding": "http://example.com/donate",

    "funding": [
        {
            "type" : "individual",
            "url" : "http://example.com/donate"
        },
        "http://example.com/donateAlso",
        {
            "type" : "patreon",
            "url" : "https://www.patreon.com/my-account"
        }
    ]
}

Users can use the npm fund subcommand to list the funding URLs of all dependencies of their project, direct and indirect. A shortcut to visit each funding url is also available when providing the project name such as: npm fund <projectname> (when there are multiple URLs, the first one will be visited)

 

펀딩

패키지 개발에 펀딩하는 방법에 대한 최신 정보를 제공하는 URL, 문자열 URL 또는 이들의 배열을 포함하는 개체를 지정할수 있다.

 

 

{
    "funding": {
        "type" : "individual",
        "url" : "http://example.com/donate"
    },

    "funding": {
        "type" : "patreon",
        "url" : "https://www.patreon.com/my-account"
    },

    "funding": "http://example.com/donate",

    "funding": [
        {
            "type" : "individual",
            "url" : "http://example.com/donate"
        },
        "http://example.com/donateAlso",
        {
            "type" : "patreon",
            "url" : "https://www.patreon.com/my-account"
        }
    ]
}

사용자는 npm fund하위 명령을 사용하여 직접 혹은 간접 프로젝트의 모든 종속성의 자금 조달 URL을 나열할 수 있다.

npm fund <projectname>과 같이 프로젝트 이름을 제공하면 각 펀딩 URL을 방문하는 바로 가기를 사용할 수 있다.(URL이 여러개인 경우 첫번째로 방문)

 

 

 ps. 해당 내용은 불필요한것 같지만 문서에 있길래 한번 넣어봤습니다..

 

files

files

The optional files field is an array of file patterns that describes the entries to be included when your package is installed as a dependency. File patterns follow a similar syntax to .gitignore, but reversed: including a file, directory, or glob pattern (*, **/*, and such) will make it so that file is included in the tarball when it's packed. Omitting the field will make it default to ["*"], which means it will include all files.

Some special files and directories are also included or excluded regardless of whether they exist in the files array (see below).

You can also provide a .npmignore file in the root of your package or in subdirectories, which will keep files from being included. At the root of your package it will not override the "files" field, but in subdirectories it will. The .npmignore file works just like a .gitignore. If there is a .gitignore file, and .npmignore is missing, .gitignore's contents will be used instead.

Files included with the "package.json#files" field cannot be excluded through .npmignore or .gitignore.

Certain files are always included, regardless of settings:

• package.json
• README
• LICENSE / LICENCE
• The file in the "main" field

README & LICENSE can have any case and extension.

Conversely, some files are always ignored:

• .git
• CVS
• .svn
• .hg
• .lock-wscript
• .wafpickle-N
• .*.swp
• .DS_Store
• ._*
• npm-debug.log
• .npmrc
• node_modules
• config.gypi
• *.orig
• package-lock.json (use npm-shrinkwrap.json if you wish it to be published)

 

파일

"files"항목(번역하면 선택적 파일 필드)은 프로젝트에 포함된 파일의 배열로 폴더 이름을 지정하면 폴더안의 파일도 포함이다.

".gitignore"와 유사하지만 그 반대라고 할 수 있다. 파일, 폴더 또는 glob 패턴(*, **/* 등)을 포함하면 압출될 때 파일이 tarball에 포함되도록 한다. 필드를 생략하면 기본저긍로 ["*"]로 지정되어 모든 파일이 포함된다.

 

파일 배열에 존재하는지 여부에 관계없이 일부 특수 파일 및 폴더도 포함되거나 제외된다.

• package.json
• README
• LICENSE / LICENCE
• The file in the "main" field

 

README & LICENSE는 모든 대소문자와 확장자를 가질 수 있다.

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

• .git
• CVS
• .svn
• .hg
• .lock-wscript
• .wafpickle-N
• .*.swp
• .DS_Store
• ._*
• npm-debug.log
• .npmrc
• node_modules
• config.gypi
• *.orig
• package-lock.json (use npm-shrinkwrap.json if you wish it to be published)

 

main

main

The main field is a module ID that is the primary entry point to your program. That is, if your package is named foo, and a user installs it, and then does require("foo"), then your main module's exports object will be returned.

This should be a module relative to the root of your package folder.

For most modules, it makes the most sense to have a main script and often not much else.

If main is not set it defaults to index.js in the package's root folder.

 

main

"main" 항목은 당신의 프로그램이 시작점이 되는 모듈의 ID이다. 즉, 패키지 이름이 foo이고 사용자가 이를 설치한 다음 require("foo")를 실행했을 때 "main"으로 지정한 모듈의 exports 객체가 반환된다.

패키지 폴더의 루트에 상대적인 모듈이어야한다. 대부분의 모듈의 경우 기본 스크립트를 갖는 것이 가장 합리적이며 다른 경우는 많지 않다.

main이 설정되지 않은 경우 기본적으로 패키지의 루트 폴더에 있는 index.js로 설정된다.

 

browser

browser

If your module is meant to be used client-side the browser field should be used instead of the main field. This is helpful to hint users that it might rely on primitives that aren't available in Node.js modules. (e.g. window)

 

browser

모듈이 클라이언트 측에서 사용되는 경우 기본 필드 대신 브라우저 필드를 사용해야한다. Node.js 모듈에서 사용할 수 없는 프리미티브에 의존할 수 있는 것을 사용자에게 암시하는데 유용하다.

 

bin

bin

A lot of packages have one or more executable files that they'd like to install into the PATH. npm makes this pretty easy (in fact, it uses this feature to install the "npm" executable.)

To use this, supply a bin field in your package.json which is a map of command name to local file name. When this package is installed globally, that file will be either linked inside the global bins directory or a cmd (Windows Command File) will be created which executes the specified file in the bin field, so it is available to run by name or name.cmd (on Windows PowerShell). When this package is installed as a dependency in another package, the file will be linked where it will be available to that package either directly by npm exec or by name in other scripts when invoking them via npm run-script.

For example, myapp could have this:

 

 

{
    "bin": {
        "myapp": "./cli.js"
    }
}

So, when you install myapp, in case of unix-like OS it'll create a symlink from the cli.js script to /usr/local/bin/myapp and in case of windows it will create a cmd file usually at C:\Users\{Username}\AppData\Roaming\npm\myapp.cmd which runs the cli.js script.

If you have a single executable, and its name should be the name of the package, then you can just supply it as a string. For example:

 

 

{
    "name": "my-program",
    "version": "1.2.5",
    "bin": "./path/to/program"
}

would be the same as this:

 

 

{
    "name": "my-program",
    "version": "1.2.5",
    "bin": {
    	"my-program": "./path/to/program"
    }
}

Please make sure that your file(s) referenced in bin starts with #!/usr/bin/env node, otherwise the scripts are started without the node executable!

Note that you can also set the executable files using directories.bin.

See folders for more info on executables.

 

 

bin

많은 패키지에는 PATH에 설치하는 하나 이상의 실행파일이 있다. npm은 이 작업을 매우 쉽게 만들수 있다. (실제로 이 기능을 통하여 "npm"실행 파일을 설치한다.)

 

이를 사용하려면 로컬파일 이름에 대한 명령 이름의 맵인 package.json에 bin필드를 제공해야 한다. 패키지 설치 시에, npm은 bin항목에 기술된 파일의 심볼릭 링크를 global install인 경우 prefix/bin에, local install인 경우 ./node_modules/.bin에 생성한다.

 

예를 들어, myapp은 다음과 같을 수 있다.

 

 

{
    "bin": {
        "myapp": "./cli.js"
    }
}

따라서 myapp을 설치할 때, 유닉스 계열 OS의 경우 cli.js 파일에 대한 심볼릭 링크가 /usr/local/bin/myapp에 만들어지고 Windows의 경우 일반적으로 C에서 cmd 파일을 생성한다. cli.js 스크립트를 실행하는 \Users\{사용자 이름}\AppData\Roaming\npm\myapp.cmd

 

단일 실행 파일이 있고 그 이름이 패키지 이름이어야 하는 경우 문자열로 제공 할 수 있다.

 

 

{
    "name": "my-program",
    "version": "1.2.5",
    "bin": "./path/to/program"
}

 

 

 

{
    "name": "my-program",
    "version": "1.2.5",
    "bin": {
    	"my-program": "./path/to/program"
    }
}

bin에서 참조하는 파일이 #!/usr/bin/env 노드로 시작하는지 확인해야한다. 그렇지 않으면 노드 실행 파일없이 스크립트가 시작된다.

 

man

man

Specify either a single file or an array of filenames to put in place for the man program to find.

If only a single file is provided, then it's installed such that it is the result from man <pkgname>, regardless of its actual filename. For example:

 

 

{
    "name": "foo",
    "version": "1.2.3",
    "description": "A packaged foo fooer for fooing foos",
    "main": "foo.js",
    "man": "./man/doc.1"
}

would link the ./man/doc.1 file in such that it is the target for man foo

If the filename doesn't start with the package name, then it's prefixed. So, this:

 

 

{
    "name": "foo",
    "version": "1.2.3",
    "description": "A packaged foo fooer for fooing foos",
    "main": "foo.js",
    "man": [
        "./man/foo.1",
        "./man/bar.1"
    ]
}

will create files to do man foo and man foo-bar.

Man files must end with a number, and optionally a .gz suffix if they are compressed. The number dictates which man section the file is installed into.

 

 

{
    "name": "foo",
    "version": "1.2.3",
    "description": "A packaged foo fooer for fooing foos",
    "main": "foo.js",
    "man": [
        "./man/foo.1",
        "./man/foo.2"
    ]
}

will create entries for man foo and man 2 foo

 

man

man 프로그램이 찾을 위치에 넣을 단일 파일 또는 파일 이름의 배열을 지정해야한다.

단일 파일만 제공된 경우 실제 파일 이름에 관계없이 man <pkgname>의 결과로 설치된다. 

예를 들어:

 

{
    "name": "foo",
    "version": "1.2.3",
    "description": "A packaged foo fooer for fooing foos",
    "main": "foo.js",
    "man": "./man/doc.1"
}

man foo의 대상이 되도록 ./man/doc.1 파일을 링크한다.

파일 이름이 패키지 이름으로 시작하지 않으면 접두사가 붙는다.

해당 예시:

 

{
    "name": "foo",
    "version": "1.2.3",
    "description": "A packaged foo fooer for fooing foos",
    "main": "foo.js",
    "man": [
        "./man/foo.1",
        "./man/bar.1"
    ]
}

man foo 및 man foo-bar를 수행하는 파일을 생성한다.

man 파일은 숫자로 끝나야 하며 압축된 경우에는 선택적으로 .gz 접미사를 붙여야 한다. 숫자는 파일이 설치된 man 섹션을 나타낸다.

 

{
    "name": "foo",
    "version": "1.2.3",
    "description": "A packaged foo fooer for fooing foos",
    "main": "foo.js",
    "man": [
        "./man/foo.1",
        "./man/foo.2"
    ]
}

man foo 및 man 2 foo에 대한 항목을 생성한다.

 

directories

directories

The CommonJS Packages spec details a few ways that you can indicate the structure of your package using a directories object. If you look at npm's package.json, you'll see that it has directories for doc, lib, and man.

In the future, this information may be used in other creative ways.

directories.bin

If you specify a bin directory in directories.bin, all the files in that folder will be added.

Because of the way the bin directive works, specifying both a bin path and setting directories.bin is an error. If you want to specify individual files, use bin, and for all the files in an existing bin directory, use directories.bin.

directories.man

A folder that is full of man pages. Sugar to generate a "man" array by walking the folder.

 

 

directories

CommonJS Packages 스펙에는 directories 개체를 사용해서 패키지 구성을 나타낼 수 있다. npm의 package.json을 보면 doc, lib와 man으로 이루어진 디렉토리가 구성된 것을 확인 할 수 있다.

앞으로 이 정보는 다른 창의적인 방식으로 사용될 수도 있다.

directories.bin

bin 디렉토리를 지정하면 해당 폴더의 모든 파일이 추가된다.

bin 지시문이 작동하는 방식으로 인해 bin경로를 지정하고 directory.bin을 설정하는 것은 오루이다. 개별 파일을 지정하려면 bin을 사용하고 기존 bin 디렉토리에 있는 모든 파일에 대해 directory.bin을 사용해야 한다.

directories.man

메뉴얼 페이지로 가득찬 폴더이다. 폴더를 이동하여 "man"배열을 생성하는 것보다 간단하다.

 

+@

directories.lib

모듈의 라이브러리가 어디에 있는지 보여준다. lib 폴더에 특별한 일을 하지는 않지만 메타 데이터로 유용하다.

directories.doc

마크다운 파일들을 여기에 위치시킨다.

directories.example

예제 파일들을 여기에 위치시킨다.