Vite + TS + React + styled-components로 구성된 프로젝트를 생성 후 초기 셋팅하던 중에 package.json을 수정할 일이 있었다. 수정을 하고 나서 문제는 해결됐지만 왜 그 부분을 수정했어야 하는지 원인을 알아야 될 것 같았다. 조사 중 우연히 알게 된 블로그에서 npm의 package.json 공식 문서를 번역한 내용을 공부해보았다.
🍰 참고 사이트
name
package.json에서 가장 중요한 항목은 'name'과 'version'이다.
이 둘을 통해 각 패키지의 고유성을 판별하며 이 항목들이 누락되면 패키지를 설치할 수 없다.
name의 규칙
- name은 반드시 214자 이하여야 한다.
- name은 점(.)이나 언더바(_)로 시작할 수 없다.
- name은 대문자를 포함할 수 없다.
- name은 URL의 일부분이므로 URL-safe하지 않은 name은 사용할 수 없다.
name 관련 조언
- Node의 코어(core) 모듈과 같은 이름을 사용하지 않는다. (같은 이름이 있는지 확인하려면 npm registry 참조)
- name에 'node' 또는 'js'라는 글자를 포함하지 않는다.
왜냐하면 package.json을 쓰고 있는 시점에서 이미 Javascript라는 것을 알 수 있기 때문이다. - name은 짧고 간결하게 짓는 것이 좋다. Javascript 파일 내에서 require() 함수의 인수로 사용되기 때문이다.
name에 접두어를 추가할 수 있다. (예: @sheryl/yenapackage)
자세한 내용은 npm-scope를 참고한다.
version
package.json에서 version이 누락되면 패키지를 설치하거나 패키지의 고유성을 판별할 수 없게 된다.
또한 패키지의 내용을 변경하려면 version을 변경해야만 한다.
description
프로젝트에 대한 설명이다. npm search로 검색된 리스트에 표시되므로 사람들이 당신이 만든 패키지를 찾아내고 이해하는 데 도움이 된다.
keywords
프로젝트와 관련된 키워드들을 String Array(문자열 배열)로 작성한다. description과 마찬가지로 npm search의 검색 리스트에 표시되기 때문에 사람들이 당신의 패키지를 찾아내고 이해하는 데 도움을 준다.
homepage
프로젝트가 배포된 링크가 있다면 여기에 입력한다.
유의
homepage는 아래 bugs의 url 항목과는 다르다. url은 외부에 설치된 패키지 소스로 리다이렉션되어 예상치 못한 상황을 발생시킬 수 있다.
bugs
프로젝트의 이슈와 버그 트래킹을 볼 수 있는 url과 이슈를 보고할 수 있는 email 주소를 작성한다. 패키지의 사용자가 패키지를 사용하다가 문제가 생겼을 때 이 곳으로 연락할 수 있다.
코드 예시
url이나 email 중 하나만 적용하는 것도 가능하며, 주로 이때는 url을 작성한다.
url만 작성하면 객체가 아닌 단순 문자열을 bugs 항목에 지정할 수 있다.
url을 지정하는 경우, npm bugs 명령을 사용할 수 있다.
"bugs": {
"url": "http://githubcom/owner/project/issues",
"email": "project@hostname.com"
}license
만들어진 패키지를 사용하기 위해 권한을 얻는 방법과 금기 사항에 대해 알려주는 정보이다.
가장 간단한 방법은 BSD-3-Clause나 MIT 같은 일반적인 라이센스의 표준 SPDX ID를 다음과 같이 지정하는 것이다.
"license": "BSD-3-Clause"https://spdx.org/licenses/에서 SPDX 라이센스 아이디 전체 리스트를 볼 수 있다.
OSI(Open Source Initiative에서 승인한 것들 중 하나를 사용하는 것이 이상적이다.
license에 대해 좀 더 자세한 사항은 이 내용을 참고한 블로그이기도 한 여기에서 확인하자.
author과 contributors
author는 한 사람만 지정할 때, contributors는 여러 사람을 지정할 때 사용한다.(배열로 작성)
name은 필수, email과 url은 선택적이다.
"author": {
"name": "Sheryl Yena Yun',
"email": "cheryleduart@gmail.com",
"url": "https://cheryl-yena-yun.com"
}다른 표기법
아래와 같이 한 줄로 줄여 입력할 수도 있다. 이렇게 하면 npm이 파싱한다.
// 형태: "name <email> (url)"
"author": "Sheryl Yena Yun <cheryleduart@gmail.com> (https://cheryl-yena-yun.com)