package.json 이란?
패키지 관리 저장소
새로운 프로젝트나 패키지를 만들 때
가장 먼저 하는 일은 npm 프로젝트로 초기화 해주는 명령어 npm init을 실행하는 것이다.
이 때 package.json 파일이 생성되는데
언뜻 봐도 프로젝트에 대한 정보를 담고 있는 중요한 파일처럼 보인다.
Node.js 프로젝트에서는 많은 패키지를 사용하게 되고
패키지의 버전도 빈번하게 업데이트 되므로,
프로젝트가 의존하고 있는 패키지를 일괄적으로 관리할 필요가 있다.
npm은 package.json 파일을 통해서
프로젝트의 정보와 패키지 의존성(dependency)을 관리한다.
package.json 파일에는 이 프로그램을 실행시키기 위해
필요한 모듈들에 대한 정보와, 프로그램을 실행시키는 방법,
프로그램을 테스트하는 방법 등이 명시되어 있다.
package.json 파일을 이용하면 협업 시
동일한 개발 환경을 빠르게 구축할 수 있다는 장점이 있다.
📌 pacakge.json 파일 생성
프로젝트의 루트 디렉토리에서 npm init 명령어를 실행하면
package.json 파일이 생성된다.
-y 또는 --yes 옵션을 추가하면 기본 설정값으로 생성된다.
npm init -ynpm init
// 기본 설정값 적용
npm init -y
npm init --yes
npm init -y를 실행하면
아래와 같이 기본 설정값이 적용된 package.json 파일이 생성된다.
{
"name": "폴더명 또는 직접 작성한 프로젝트명",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "ISC"
}📌 pacakge.json의 프로퍼티
각 프로퍼티는 JSON 형식의 key: value 형태로 구성된다.
name과 version을 통해서 각 패키지의 고유성을 판별하기 때문에,
각각의 정보는 키, 값 이 쌍으로 저장되는 단일 JSON 객체로 구성됩니다.
배포될 패키지라면 이 두 프로퍼티가 가장 중요하다.
- 🌟 name
- 🌟 version
- 🌟 description
- ⭐ main
- ⭐ type
- ⭐ scripts
- ⭐ dependencies
- ⭐ devDependencies
- keywords
- homepage
- bugs
- license
- author
- contributors
- files
- bin
- directories
- repository
- config
- engine
- private
📌 name
프로젝트 이름으로, 가장 중요합니다.
중앙 저장소에 배포할 때 version과 함께 필수 항목입니다.
url로 사용되고, 설치할 때 디렉토리 이름이 되기 때문에 url이나 디렉터리에서 쓸 수 없는 이름을 사용하면 안 됩니다.
또한, 이름에 node나 js가 들어가면 안 됩니다.
name은 214자보다 짧아야 하며, 점( . )이나 밑줄( _ )로 시작할 수 없습니다.
대문자를 포함해서는 안 되며,
require() 함수의 인수로 사용되며 짧고 알기 쉬운 것으로 짓는 것이 좋습니다.
{
"name": "test-for-studying",
}📌 version
프로젝트의 현재 버전을 정의합니다.
버전은 항상 세 자리로 이루어져 있습니다.
이는 SemVer 방식의 버전 넘버링을 따르기 때문입니다.
Senver는 Semantic Versioning(유의적 버전)의 약어로 버전을 구성하는 세 자리 모두 의미를 가지고 있다는 뜻입니다.
{
"version": "1.0.0",
}🏷️ Semantic Versioning (semver)
버전 정보는 아래와 같이 유의적으로 구성되어 있다.
- 메이저 버전 번호 : 하위 호환이 되지 않는 변경 사항
- 마이너 버전 번호 : 하위 호환이 되는 변경 사항
- 패치 버전 번호 : 간단한 버그 수정
| 표기법 | 설명 |
| version | 명시된 version과 일치 |
| >version | 명시된 version보다 높은 버전 |
| >=version | 명시된 version과 같거나 높은 버전 |
| <version | 명시된 version보다 낮은 버전 |
| <=version | 명시된 version과 같거나 낮은 버전 |
| ~version | 명시된 version과 근사한 버전 (패치 버전 범위 내) |
| ^version | 명시된 version과 호환되는 버전 (마이너 버전 범위 내) |
~(틸드) : 패치 버전 범위 내에서 업데이트 (ex. ~0.1.1: 0.1.1 <= version < 0.2.0)
^(캐럿) : 마이너 버전 범위 내에서 업데이트 (ex. ^1.0.2: 1.0.2 <= version < 2.0.0)
1.2 - 1.4 : 해당 버전 사이 명시
ex) ^1.2.3 → 해당 버전과 호환되는 버전 명시
내가 1.2.3으로 개발했는데
이걸로 호환되는걸로 최근 버전으로 사용해라는 뜻
📌 description
프로젝트 설명으로, 문자열로 기술합니다.
npm search로 검색된 리스트에 표시되기 때문에 사람들이 패키지를 찾아내고 이해하는 데 도움이 됩니다.
{
"description": "An example module to study the usage of package.json",
}📌 main
프로그램의 기본 진입점이 되는 모듈 ID입니다.
패키지 첫 번째 실행할 '파일명' 작성
ex) "main": "test.js"
→ test.js 기반으로 동작한다.
{
"main": "filename.js"
}📌 type
프로젝트 단위의 ES 모듈 적용
파일 각각 적용하지 않고, 프로젝트 전체에 적용할 때 설정합니다.
type 필드는 commonjs(기본 값)와 module 중 하나를 사용할 수 있습니다.
type 필드가 정의되어 있지 않다면 commonjs로 처리됩니다.
아래와 같이 작성할 수 있습니다.
파일의 확장자가 .mjs이거나 type 필드가 module일 경우
패키지는 ES Module를 사용하여 import나 import() 함수를 사용할 수 있게 됩니다.
파일 확장자가 .cjs이거나 type 필드가 commonjs일 경우(혹은 생략)
import, import() 함수, require() 함수를 사용할 수 있습니다.
{
"type": "module"
}{
"type": "commonjs"
}📌 scripts
명령어를 미리 작성해두고 간편하게 명령어를 실행하는 단축 명령어 집합
스크립트는 간단한 빌드 프로세스 또는 개발 도구와 같은 패키지와 관련된 작업을 자동화하는 좋은 방법입니다.
프로젝트에서 자주 실행해야 하는 명령어를 scripts로 작성해두면 npm 명령어로 실행 가능합니다.
npm start → "start" 명령어 실행
npm build → "build" 명령어 실행
npm test → "test" 명령어 실행
start, build, test 는 그냥 사용이 가능한데
그 외 이름을 가진 스크립트는
npm run Name 식으로 작성해야 실행 (run 붙힌다.)
{
"scripts": {
"dev": "gulp dev",
"build": "gulp build",
"deploy": "gulp deploy"
},
}
사용예시
"scripts": {
"start": "node -v",
"test": "echo \"Error: no test specified\" && exit 1"
}
// ▶ 터미널 실행 → npm start
사용예시
"scripts": {
"tt": "node -v",
"start": "node -v",
"test": "echo \"Error: no test specified\" && exit 1"
}
// ▶ 터미널 실행 → npm run tt📌 dependencies
프로젝트 의존성 관리를 위한 부분이며, npm 종속성으로 설치된 패키지 목록을 설정합니다.
npm 또는 yarn을 사용하여 패키지를 설치하면 dependencies 목록에 자동으로 등록됩니다.
npm install <module_name>
예를 들어, npm으로 uxkm-sass라는 패키지를 설치하면
아래처럼 dependencies에 설치한 uxkm-sass가 자동 등록됩니다.
{
"dependencies": {
"uxkm-sass": "^1.0.2"
// 패키지명 : 설치된 버전
}
}📌 devDependencies
패키지를 개발할 때만 필요하지만 프로덕션 환경에서는 설치되지 않는 패키지입니다.
개발할때만 쓰고, 추출/실행할 때는 안됨
npm install <module_name> -D
예를 들어, npm으로 uxkm-gulp라는 패키지를 설치하면
아래처럼 devDependencies에 설치한 uxkm-gulp가 자동 등록됩니다.
{
"dependencies": {
"uxkm-gulp": "^1.0.2"
// 패키지명 : 설치된 버전
}
}
사용예시
// ▶ 터미널 실행 → npm i -D react
// 'package.json' 파일 → 아래와 같이 코드 추가됨
"devDependencies": {
"react": "^18.3.1"
}📌 keywords
프로젝트를 검색할 때 참조되는 키워드입니다.
description과 마찬가지로 npm search로 검색된 리스트에 표시됩니다.
{
"keywords": ["fruits", "Apple", "Persimmon", "Pomegranate", "Jujube", "Mango", "Yuja"]
}📌 homepage
프로젝트 홈페이지 주소입니다.
url 항목과는 다르며, url을 설정하면 예상치 못한 움직임을 하게 되므로 주의해야 합니다.
{
"homepage": "https://your-package.org"
}📌 bugs
프로젝트 이슈와 버그 트래킹을 볼 수 있는 url과 이슈를 알릴 email 주소를 입력합니다.
패키지 사용자가 문제에 직면했을 때 도움을 주기 위함입니다.
url, email 중 하나 또는 두 값을 모두 지정할 수 있습니다.
url 이 제공되면 npm bugs 명령을 사용할 수 있습니다.
// url, email 모두 사용
{
"bugs": {
"url" : "https://github.com/owner/project/issues",
"email" : "project@hostname.com"
}
}
// url 만 사용
{
"bugs": {
"url" : "https://github.com/owner/project/issues"
},
// 또는
"bugs": "https://github.com/owner/project/issues"
}📌 license
배포한 패키지에 대해 패키지 사용자가 패키지를 사용하는데
어떤 권한과 제한 사항이 있는지 알기 위해 license를 명시해야 합니다.
{
"license": "MIT",
"license": "(MIT or GPL-3.0)",
"license": "SEE LICENSE IN LICENSE_FILENAME.txt",
"license": "UNLICENSED"
}📌 author
프로젝트 작성자 정보로, 한 사람만을 지정합니다.
name은 필수 요소이며, 선택 요소로 email, url을 추가할 수 있습니다.
{
"author": {
"name": "Your Name",
"email": "you@example.com",
"url": "http://your-website.com"
},
// 또는
"author": "Your Name <you@example.com> (http://your-website.com)"
}📌 contributors
프로젝트에 참여한 공헌자 정보로, 여러 사람을 배열로 지정할 수 있습니다.
{
"contributors": [
{ "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
{ "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
],
// 또는
"contributors": [
"Your Friend <friend@example.com> (http://friends-website.com)",
"Other Friend <other@example.com> (http://other-website.com)"
]
}📌 files
프로젝트에 포함된 파일입니다.
단일 파일 또는 특정 디렉토리를 지정하거나 와일드카드를 사용하여
특정 기준을 충족하는 파일을 포함할 수 있습니다.
{
"files": ["filename.js", "directory/", "glob/*.{js,json}"]
// 단일 파일, 특정 폴터, 기준을 충족하는 파일
}📌 bin
많은 패키지는 PATH에 설치되는 하나 이상의 실행 파일을 가지고 있습니다.
npm에서는 이를 매우 쉽게 구현할 수 있습니다.
(실제로 이 기능은 "npm"을 설치하는 데에도 사용되고 있습니다.)
실행할 수 있는 패키지를 만들기 위해선 package.json 파일에 bin 항목을 제공해야 합니다.
패키지 설치 시에,
npm 은 bin 항목에 기술된 파일의 심볼릭 링크를
global install인 경우 prefix/bin 에
local install인 경우 ./node_modules/.bin/ 에 생성하게 됩니다.
{
"bin": { "myapp": "./cli.js" }
}
그래서 myapp을 설치할 때, cli.js 파일에 대한 심볼릭 링크가 /usr/local/bin/myapp에 만들어집니다.
만약, 하나의 실행 파일만 가지고 있다면, 실행 파일의 이름은 패키지의 이름과 같게 되고,
{
"bin": {
"command-name": "bin/command-name.js",
"other-command": "bin/other-command"
}
}
그렇게 않다면 아래와 같이 각각의 실행 파일의 이름을 bin 항목에 지정해 주어야 합니다.
📌 directories
CommonJS Packages 스펙에는 directories 개체를 사용해서 패키지 구성을 나타낼 수 있습니다.
npm의 package.json을 보면 doc, lib, man으로 이루어진 디렉토리 구성을 확인할 수 있습니다.
앞으로 이 정보는 다른 창의적인 방법으로 사용될 수 있습니다.
{
"directories": {
"lib": "path/to/lib/",
// 모듈의 라이브러리가 어디에 있는지 보여줍니다. lib 폴더에 특별한 일을 하지는 않지만 메타 데이터로 유용합니다.
"bin": "path/to/bin/",
// 만약 directories.bin로 bin을 지정하면, 해당 디렉토리의 모든 파일이 실행 파일로 추가됩니다.
// bin 이 동작하는 방식에 의해, bin 과 directories.bin 을 모두 지정하면 오류가 발생합니다.
// 각각의 파일을 지정하고 싶다면 bin을 특정 폴더 아래의 모든 파일을 bin으로 지정하고 싶다면
// directories.bin을 사용해야 합니다.
"man": "path/to/man/",
// man 문서들이 위치한 폴더를 가리킵니다. "man" 배열을 만드는 것보다 간편합니다.
"doc": "path/to/doc/",
// 마크다운 파일들을 여기에 위치시킵니다.
"example": "path/to/example/"
// 예제 파일들을 여기에 위치시킵니다.
}
}
📌 repository
프로젝트의 소스 코드를 저장한 저장소의 정보입니다.
소스 코드에 참여하고자 하는 사람들에게 도움이 될 수 있고,
만약 git 저장소가 github라면 npm docs 명령으로 찾을 수 있습니다.
{
"type": "git",
"url": "https://github.com/user/repo.git"
}📌 config
스크립트에 사용된 구성 옵션 또는 매개변수입니다.
{
"config": {
"port": "8080"
}
}📌 engine
이 패키지/앱이 작동하는 Node.js 및 기타 명령의 버전을 설정합니다.
{
"engines": {
"node": ">= 6.0.0",
"npm": ">= 3.0.0",
"yarn": "^0.13.0"
}
}📌 private
패키지 관리자에 패키지를 게시하지 않을 때 설정합니다.
개인적으로만 사용하는 저장소를 패키지 관리자에 무심코 개시하는 것을 방지합니다.
{
"private": true
}
'📌 Front End > └ Node.js' 카테고리의 다른 글
| [Node.js] Nodejs 모듈(CommonJS / ES Modules) (0) | 2024.08.09 |
|---|---|
| [Node.js] Package.json 명령어 npm start, npm run build 스크립트 차이점 (1) | 2024.08.09 |
| [Node.js] Node 개념 및 기본 명령어 (0) | 2024.08.09 |
