package.json 파일 파헤치기
자바스크립트 프로젝트를 시작할 때 가장 먼저 마주하게 되는 package.json 파일에 대해 얼마나 알고 계신가요? 이 파일은 단순히 의존성을 나열하는 목록을 넘어, 자바스크립트 프로젝트의 정체성을 정의하고 동작 방식을 결정하는 핵심적인 역할을 합니다.
package.json은 프로젝트의 이름과 버전 같은 기본 정보부터 시작해, 실행에 필요한 의존성 패키지 관리, npm run으로 실행되는 각종 스크립트 설정에 이르기까지 프로젝트의 모든 메타데이터를 담고 있습니다. 하지만 많은 개발자가 초기 설정 이후에는 이 파일을 깊이 들여다보지 않거나, dependencies나 scripts 같은 일부 필드에만 익숙할 때가 많습니다.
이번 글에서는 name, version과 같은 기본적인 필드부터 workspaces, exports, overrides와 같이 프로젝트의 구조와 배포 방식을 지정할 수 있는 고급 필드까지, package.json에서 사용할 수 있는 다양한 필드를 하나씩 살펴보고자 합니다. 이 파일을 제대로 이해하고 활용하는 것은 프로젝트의 완성도를 높이고 협업을 원활하게 만드는 첫걸음이 될 것입니다.
package.json의 주요 필드
name
프로젝트의 이름을 정의하는 필드입니다.
npm 레지스트리에 배포하거나 다른 프로젝트에서 참조할 목적이 아니라면 필수 항목은 아니지만 프로젝트를 npm 레지스트리를 통해 공유할 필요가 있다면 레지스트리 내에서 고유한 명칭을 지정해야 합니다.
scope
name 필드에 사용되며, @scope/packagename과 같은 형태로 작성됩니다.
@scope 부분은 특정 사용자나 조직에 귀속되므로 다른 사용자는 해당 스코프를 사용할 수 없습니다.
@babel/*, @toss/*처럼 연관된 패키지를 그룹화하거나, 기업 브랜드를 나타내기 위해 사용됩니다.
version
패키지의 버전을 나타냅니다.
npm 레지스트리에 배포할 경우 name과 version의 조합은 항상 고유해야 합니다.
패키지가 업데이트될 때마다 이 버전 정보도 함께 변경해야 합니다.
description
패키지에 대한 설명을 문자열로 기재하는 필드입니다.
npm info <패키지명> 명령어를 통해 해당 내용을 확인할 수 있습니다.
keywords
패키지와 관련된 키워드를 문자열 배열 형태로 입력합니다.
이 정보 역시 npm info <패키지명> 명령어로 조회가 가능합니다.
homepage
패키지의 홈페이지 URL을 기재하는 필드입니다.
주로 깃허브 저장소 주소나 별도의 소개 사이트 주소를 입력합니다.
bugs
패키지에서 버그 발생 시 제보할 수 있는 URL이나 이메일 주소를 기재합니다.
객체 형태({ "url": "...", "email": "..." }) 또는 문자열 형태로 작성할 수 있습니다.
license
패키지의 라이선스를 명시해서 사용 범위와 제한 사항을 알립니다.
오픈소스 라이선스의 SPDX ID 값을 기재하는 것이 일반적입니다.
author / contributors
author에는 주 제작자 한 명을, contributors에는 여러 기여자를 명시합니다.
두 필드 모두 이름(name), 이메일(email), URL(url)을 포함하는 객체 형태로 작성할 수 있습니다.
funding
프로젝트에 대한 후원 방법을 입력하는 필드입니다.
URL, 객체, 배열 등 다양한 형식으로 자유롭게 작성할 수 있습니다.
files
npm 레지스트리에 패키지를 배포할 때 포함될 파일 및 디렉터리 목록을 지정합니다.
이 필드를 활용하면 불필요한 파일을 제외해서 패키지 크기를 최적화할 수 있습니다.
.npmignore 파일이 있으면 files 필드보다 우선시되어 특정 파일이 제외될 수 있으므로 사용할 때 주의가 필요합니다.
main
패키지의 진입점이 되는 파일을 지정합니다.
사용자가 require("패키지명")을 호출했을 때, 이 필드에 명시된 파일이 로드됩니다.
별도로 설정하지 않으면 index.js가 기본값으로 사용됩니다.
browser
패키지가 브라우저 환경에서 사용될 때를 위한 진입점 파일입니다.
main 필드를 대체하며, 웹팩과 같은 번들러가 이 필드를 참조합니다.
bin
패키지에 포함된 실행 가능한 파일의 위치를 지정합니다.
패키지를 전역(-g 옵션을 사용해)으로 설치하면 여기에 명시된 파일을 터미널에서 명령어로 직접 실행할 수 있습니다.
man
유닉스 시스템의 man 명령어를 통해 볼 수 있는 매뉴얼 파일의 위치를 지정합니다.
최근에는 웹사이트나 깃허브를 통해 문서를 제공하는 경우가 많아 거의 사용되지 않는 필드입니다.
directories
lib, src, docs 등 프로젝트 내 여러 디렉터리의 위치를 명시하는 필드입니다.
이 필드 역시 현대적인 프로젝트에서는 자주 사용되지 않습니다.
repository
패키지의 소스코드가 저장된 원격 저장소의 정보를 기재합니다.
scripts
프로젝트에서 자주 사용하는 명령어들을 단축키처럼 등록해서 사용하는 필드입니다.
npm run <명령어>를 통해 실행할 수 있으며, pre, post 접두사를 이용해 특정 스크립트의 실행 전후에 다른 명령어를 자동으로 실행시킬 수 있습니다.
config
scripts에서 사용할 환경 설정 값들을 객체 형태로 저장하는 필드입니다.
dependencies
프로젝트가 실제로 실행될 때 반드시 필요한 외부 패키지들의 목록과 버전 범위를 정의합니다.
overrides
현재 프로젝트가 의존하는 패키지가 또 다른 패키지에 의존할 때 그 하위 패키지의 버전을 강제로 지정하고 싶을 때 사용합니다.
engines
패키지가 정상적으로 동작하는 데 필요한 Node.js의 버전 범위를 명시합니다.
os
패키지가 호환되는 운영체제(OS)를 배열 형태로 지정합니다. (예: "os": ["darwin", "linux"])
cpu
패키지가 호환되는 CPU 아키텍처를 배열 형태로 지정합니다. (예: "cpu": ["x64", "arm64"])
private
이 값을 true로 설정하면 실수로라도 해당 패키지가 npm 레지스트리에 배포되는 것을 방지할 수 있습니다.
publishConfig
패키지를 배포할 때 사용될 설정 값을 정의합니다.
기본 npm 레지스트리가 아닌 다른 주소에 배포할 때 유용합니다.
workspaces
하나의 상위 프로젝트에서 여러 하위 패키지를 관리하는 모노레포 방식을 위해 사용됩니다.
하위 패키지들이 공통의 node_modules를 참조하게 해서 효율적인 관리를 돕습니다.
packageManager
해당 프로젝트에서 사용해야 할 패키지 매니저(npm, yarn, pnpm)와 버전을 지정하는 실험적인 기능의 필드입니다.
type
Node.js가 프로젝트의 자바스크립트 파일을 어떤 모듈 시스템으로 해석할지 결정합니다.
"module"로 설정하면 ESModule 방식으로, "commonjs" 또는 설정하지 않을 경우에는 CommonJS 방식으로 동작합니다.
exports
main 필드의 대안으로, 패키지의 진입점을 더 상세하고 조건부로 설정할 수 있게 합니다.
다양한 환경에 따라 다른 진입점을 제공할 수 있습니다.
imports
해당 패키지 내부에서만 사용할 수 있는 경로 별칭(alias)을 지정하는 기능입니다.
예를 들어, #components/Button과 같은 형태로 특정 파일을 불러올 수 있도록 설정할 수 있습니다.
지금까지 package.json의 수많은 필드와 그 역할을 살펴보았습니다. 보신 바와 같이 이 파일은 단순한 설정 파일을 넘어 프로젝트를 더욱 견고하고 효율적으로 만들어주는 강력한 도구로서 package.json 파일에 대한 깊이 있는 이해는 여러분을 더욱 노련한 자바스크립트 개발자로 만들어 줄 것입니다.
더 자세한 내용이 궁금하신 분들께 《npm Deep Dive》를 추천합니다. 《npm Deep Dive》에서는 이번 글에서 다룬 내용을 비롯해 자바스크립트 생태계에서 사용되는 다양한 도구와 개념의 작동 원리와 선택 기준을 깊이 있게 다루고, 자바스크립트 생태계의 핵심을 체계적으로 다룹니다.
초보 개발자라면 복잡한 개념을 단계적으로 이해할 수 있도록, 숙련된 개발자라면 실무에 바로 적용할 수 있는 팁과 전략을 통해 자바스크립트를 한층 더 깊이 이해하고 활용할 수 있도록 도와드립니다. 이 책을 통해 자바스크립트 생태계를 한층 더 깊이 있게 이해하고, 더 나은 개발 환경을 만드는 것뿐만 아니라 평소에 하던 웹 서비스 개발만으로는 이해하기 힘든 지식을 얻을 수 있을 것입니다.
