Node.js - package.json 설정하기(setting)

Node.js

package.json 설정하기

 

🔎 package.json 란

package.json 란 npm(또는 yarn, pnpm) 으로 관리되는 node.js 기반의 프로젝으에 대한 상세 이자 해당 프로젝트에서 관리하는 module 의 의존성에 대한 상세를 모아놓은 파일이다. 즉, 해당 프로젝트에 대한 전반적인 상세를 기술해 놓은 파일이라 할 수 있다.

 

package.json 은 파일명에서도 알 수 있지만 json 형식의 파일이고 필수적인 항목으로 name, version 이 있으며, 그 외에도 다양한 항목이 있다. 이 후부터는 package.json 의 여러 항목에 대해 알아보도록 하자.

 

🔎 name

name 이란 단어에서 알 수 있듯이 프로젝트의 고유한 이름을 나타낸다. 위에서 언급한 내용처럼 name 과 version 은 프로젝트에 필수적인 요소이며 이 2가지 요소를 통해 고유성을 판단한다. name 에는 몇가지 규칙과 Tip이 있다.

 

규칙

• 반드시 214자보다 짧아야한다.
• 점(.) 이나 밑줄(_) 로 시작할 수 없다.
• 대문자를 포함할 수 없다
• URL 의 일부이고 커맨드라인의 인수이자 폴더명으로 URL-safe 하지 않은 문자는 거부된다.

Tips

• Node 의 코어 module 과 같은 이름을 사용하지 않는다.
• 'node' 나 'js' 를 포함하지 않는다. 
• JavaScript 내에서 require() 문에 사용되기 때문에 되도록 짧고 알기 쉽게 설정한다.
• 설정 전에 이미 사용되고 있는지 확인한다. (https://www.npmjs.com/)

추가로 name 에는 scope 에 의해 접두어가 추가될 수 있다. 자세한 내용은 npm-scope 를 통해 확인할 수 있다.

 

🔎 version

name 과 마찬가지로 프로젝트의 필수적인 요소이며 패키지의 버전을 나타낸다. 해당 패키지의 업그레이드 및 수정사항 등 변경사항을 적용하기 위해서는 version 을 변경해야만 한다.

 

version 은 Semantic Versioning 형태로 관리된다.

 

🔎 description

프로젝트에 대한 설명으로 npm 에서 해당 패키지를 검색하거나 패키지를 이해하는데 도움을 주는 항목이다.

 

🔎 keywords

해당 프로젝트에 대한 keyword 를 문자열 배열로 나타낸다. npm 에서 해당 패키지를 검색할 때 도움을 준다.

 

🔎 homepage

해당 프로젝트에 대한 homepage 가 있을 경우 작성한다. 

 

※ homepage 는 url 항목과는 다르다. url 과 혼용하여 사용할 경우 예상치 못한 동작을 하게 된다. 

 

🔎 bugs

프로젝트에 issue 나 bug 를 트래킹해 볼 수 있는 url 이나 이를 알릴 수 있는 email 주소를 나타내는 항목이다. 

url 또는 email 중 하나만 적용이 가능하며 url 만 지정할 경우 bugs 항목에 string 으로 바로 지정할 수 있다.

{
  ...,
  "bugs": {
    "url": "https://..."
    // 또는
    "email": "email@domain.com"
  },
  ...
}

// 또는

{
  ...,
  "bugs": "https://...",
  ...
}

 

🔎 license

사용자들이 해당 패키지를 사용하기 위해 어떻게 권한을 얻고 어떤 금기사항이 있는지 확인하기 위해 작성하는 항목이다.

 

🔎 author & contributors

두 항목 모두 해당 프로젝트에 대한 작성자 (혹은 기여자) 를 나타내는 항목으로 author 는 한사람만 지정하는 경우, contributors 는 여러사람을 지정할 때 사용된다. name 은 필수이며 email 이나 url 은 선택적으로 기입한다.

{
  ...,
  "author": {
    "name": "your name",
    "email": "email@domain.com",
    "url": "https://yourhomepage.com"
  },
  // 또는
  "contributors": [
    {
      "name": "your name",
      "email": "email@domain.com",
      "url": "https://yourhomepage.com"
    },
    ...
  ],
  ...
}

 

🔎 files

해당 프로젝트에 포함된 파일들을 나타내는 항목이다. 폴더 이름을 지정하면 폴더 안의 파일도 포함된다. .npmignoire 파일에 포함된 파일이라면 해당 항목에 기록되어 있더라도 제외된다.

 

이와 별개로 항상 포함되거나 항상 무시되는 파일이 존재한다.

 

항상포함

• package.json
• README
• CHANGELOG
• LICENSE or LICENCE

항상무시

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

 

🔎 main

해당 프로젝트의 시작점이 되는 ID 로 사용자가 해당 패키지를 받아 require 하였을 경우 반환되는 곳을 나타낸다. 이 부분에 기입되는 ID 는 상대적인 경로로 지정해야 한다.

 

🔎 bin

해당 프로젝트에서 실행 가능한 JavaScript 파일을 상위에 노출시키기 위해 사용되는 항목이다. 많이 사용되는 create-react-app 의 bin 설정을 보면 아래와 같다.

{
  ...,
  "bin": {
    "create-react-app": "./index.js"
  },
  ...
}

 

🔎 directories

CommonJS Package 스펙에서 패키지의 구성을 나타내기 위해 사용되는 항목이다. 

 

구성

• directories.bin : 해당 디렉토리의 모든 파일이 실행파일로 추가된다. bin 속성과 동일하고 2가지 중 1개만 사용한다.
• directories.lib : 해당 모듈의 라이브러리의 위치를 나타낸다. 
• directories.man : man 문서들의 위치를 나타낸다. man 필드에 배열로 설정하는 것 보다 간단하게 설정할 수 있다.
• directories.doc : 마크다운 파일의 위치를 나타낸다.
• directories.example : 예제파일의 위치를 나타낸다.

 

🔎 repository

해당 프로젝트의 소스코드가 관리되는 저장소의 위치를 나타낸다. 

{
  ...,
  "repository": {
    "type": "git",
    "url": "https://github.com/myrepo/project.git"
  },
  // 또는
  "repository": {
    "type": "git",
    "url": "https://github.com/myrepo/project.git",
    "directory": "packages/front"
  },
  // 또는
  "repository": {
    "type": "svn",
    "url": "https://domain.com/svn/project",
  },
  ...
}

 

🔎 scripts

해당 패키지에서 실행되는 script 명령들을 나타내는 항목이다. npm run <key> 또는 yarn <key> 또는 pnpm <key> 로 커맨드 라인에서 실행되며 이 때 실행되는 커맨드를 값으로 가진다.

{
  ...,
  "scripts": {
    // "key": "값",
    "dev": "webpack-dev-server --mode development --open --hot",
    "build": "webpack --mode production",
    "start": "webpack --mode development",
    "lint": "eslint .",
    "lint-staged": "lint-staged"
  },
  ...
}

 

🔎 dependencies

해당 프로젝트에서 사용되는 종속성(의존성) 을 나열하는 속성이다. 패키지의 이름과 해당 패키지의 버전 범위를 같이 사용하는 것으로 사용할 수 있다.

{
  ...,
    "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-icons": "^4.11.0",
    "react-router-dom": "^6.18.0",
    "styled-components": "^6.1.0"
  },
  ...
}

version:  범위 지정
version : 명시한 version 과 일치해야 한다.
>version : 명시한 version 보다 높아야 한다.
>=version : 명시한 version 보다 같거나 높아야 한다.
<version : 명시한 version 보다 낮아야 한다.
<=version : 명시한 version 보다 같거나 높아야 한다.
~version : 명시한 version 과 근사한 버전.
^version : 명시한 version 과 호환되는 버전.
1.2.x : 1.2.0, 1.2.1 등 
* : 모든 버전
" " : * 과 같음
version1 - version2 : version1 과 version2 사이
range1 || range2 : range1 or range2
path/path/path : 해당 로컬 경로에 해당하는 패키지

 

🔎 devDependencies

dependencies 와 동일하지만 개발단계에서만 사용되는 종속성(의존성) 을 나타내는 항목이다. 패키지는 로컬에 설치되지만 패키지를 사용하는 사용자에게는 설치되지 않는다. 사용법은 dependencies 와 동일하다.

 

🔎 peerDependencies

상속 받아야하는 종속성(의존성)을 나타내는 항목으로 해당 패키지가 사용되는데 있어서 사용자에게 제공받아야만 하는 모듈들을 나타낸다. 사용법은 dependencies 와 동일하다.

 

🔎 bundleDependencies

해당 패키지를 배포할 때 번들링 되는 모듈들을 나타낸다. 패키지의 이름의 배열로 나타낸다.

{
  ...,
  "bundleDependencies": [
    "renderized",
    "super-streams"
  ],
  ...
}

 

🔎 optionalDependencies

해당 프로젝트에서 선택적으로 종속된 패키지를 나열한다. 해당 패키지를 설치할 때 optionalDependencies 에 나열된 패키지들은 없거나 설치에 실패하더라도 설치가 진행된다. 사용법은 dependencies 와 동일하다.

 

🔎 engines

해당 프로젝트가 동작 가능한 node의 버전이나 패키지 매니저(npm, yarn, pnpm) 의 버전을 지정하는 속성이다. .npmrc 에 engin-strict 가 설정되어 있지 않다면 해당 속성은 권고 사항으로 취급된다.

{
  ...,
  "engines": {
    "node": ">=0.10.3 <15",
    "npm": "~1.0.20",
    "yarn": "~1.19.0",
    "pnpm": ">=3"
  },
  ...
}

 

🔎 os

해당 패키지가 어떤 운영체제에서 작동하는지를 나타낸다. 블랙리스트 방식과 화이트리스트 방식으로 표현할 수 있다.

{
  ...,
  "os": ["darwin", "linux"],
  // 또는
  "os": ["!win32"],
  ...
}

 

🔎 cpu

해당 패키지가 동작할 수 있는 CPU 를 나타낸다. OS 설정과 동일하게 블랙리스트 방식과 화이트리스트 방식으로 표현할 수 있다.

 

🔎 preferGlobal

해당 패키지가 글로벌로 설치되어야 하는지를 나타낸다. true 일 경우 local 설치 시 경고를 표시한다. 하지만 완전하게 막을 수는 없다.

 

🔎 private

해당 패키지의 배포 여부를 나타낸다. false 일 경후 패보되지 않는다.

 

🔎 publishConfig

해당 패키지를 배로할 때 설정들을 오버라이드 할 수 있는 속성이다. 패키지 매니저에 따라 오버라이드 가능 한 설정들이 다르기 때문에 작성 전 사용하는 패키지 매니저의 설명을 참고하여 작성한다.

 

🔎 workspace

해당 프로젝트를 모노레포 로 구성할 경우 하위 프로젝트의 경로를 표시하는 속성이다. 패키지 매니저에 따라 지원을 안 할 수도 있다. (pnpm 의 경우 workspace 가 아닌 pnpm-workspace.yaml 파일을 통해 관리한다.)

 

 

 

참고
https://programmingsummaries.tistory.com/385
https://beomy.github.io/tech/etc/package-json/