package.json 파일의 역할 및 구조

 

package.json 파일의 역할

package.json 파일은 한마디로 "Node.js 프로젝트의 주민등록증이자 상세한 사용 설명서" 

이 파일은 프로젝트에 대한 모든 핵심 정보를 담고 있으며, 다음과 같은 중요한 역할을 수행한다.

 

1. 프로젝트 식별: 프로젝트의 이름, 버전, 설명, 라이선스 등 기본적인 정보를 명시하여 어떤 프로젝트인지 식별할 수 있게 함. 
2. 의존성 관리: 프로젝트가 실행되거나 개발되기 위해 필요한 외부 패키지(라이브러리)들의 목록과 버전을 관리한다. npm이나 pnpm 같은 패키지 매니저는 이 파일을 보고 필요한 패키지를 자동으로 설치한다.
3. 스크립트 실행: build, test, start 등 반복적으로 사용되는 터미널 명령어들을 짧은 스크립트로 정의하여, 모든 팀원이 동일한 명령어로 프로젝트를 제어할 수 있게 한다.
4. 버전 관리: 프로젝트의 버전을 명확하게 관리하여, 변경 사항을 추적하고 다른 사용자들이 특정 버전을 사용할 수 있도록 한다. 
5. 진입점 명시: 이 프로젝트가 라이브러리로 사용될 때, 외부에서 import 또는 require 했을 때 어떤 파일을 가장 먼저 읽어야 하는지 알려주는 이정표 역할을 한다.

 

 

패키지란 재사용 가능한 코드 묶음

→ 보통 하나의 기능 또는 라이브러리를 구현한 코드 집합이며, package.json 파일을 통해 정의됨

// package.json

{
  "name": "@my-company/ui-kit",
  "version": "1.2.5",
  "description": "A reusable UI component library for My Company projects.",
  "keywords": [
    "react",
    "ui",
    "components"
  ],
  "license": "MIT",
  "author": "Gemini AI <gemini@google.com>",
  "repository": {
    "type": "git",
    "url": "https://github.com/my-company/design-system.git"
  },
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "type": "module",
  "files": [
    "dist"
  ],
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "jest",
    "lint": "eslint src/",
    "storybook": "storybook dev -p 6006"
  },
  "dependencies": {
    "clsx": "^2.1.1"
  },
  "devDependencies": {
    "@testing-library/react": "^16.0.0",
    "@types/react": "^18.3.3",
    "eslint": "^8.57.0",
    "jest": "^29.7.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "storybook": "^8.1.10",
    "typescript": "^5.4.5",
    "vite": "^5.2.13"
  },
  "peerDependencies": {
    "react": ">=18.0.0",
    "react-dom": ">=18.0.0"
  }
}

 

1. 필수적인 식별 정보

• name: 패키지 이름. npm 레지스트리에 배포할 경우 고유해야 함. 보통 소문자와 하이픈(-)만 사용.
• version: 패키지의 현재 버전. SemVer(유의적 버전) 규칙(MAJOR.MINOR.PATCH)을 따르는 것이 표준입니다.
  • PATCH: 버그 수정 (예: 1.0.0 → 1.0.1)
  • MINOR: 하위 호환성을 유지하는 새로운 기능 추가 (예: 1.0.1 → 1.1.0)
  • MAJOR: 하위 호환성이 깨지는 큰 변경 (예: 1.1.0 → 2.0.0)

 

2. 부가적인 설명 정보

• description: 패키지에 대한 간결한 설명
• keywords: npm 검색 시 사용될 키워드 배열. (예: ["react", "ui", "component"])
• license: 패키지의 라이선스. (예: "MIT", "ISC")
• author: 패키지 제작자 정보
• repository: 코드 저장소의 주소 (예: {"type": "git", "url": "https://github.com/..."})

 

3. 의존성 관리 (가장 중요)

dependencies: 프로덕션 환경에서 애플리케이션이 동작하는 데 필요한 패키지

• 예시: react, express, axios

• devDependencies: 개발 환경에서만 필요한 패키지들입니다. (테스트, 빌드, 코드 포맷팅 등) 실제 서비스에는 포함되지 않음
  • 예시: typescript, eslint, jest, vite, storybook
• peerDependencies: 내 패키지가 제대로 동작하기 위해, 이 패키지를 설치하는 프로젝트가 반드시 가지고 있어야 하는 패키지들을 명시 (예: React 컴포넌트 라이브러리의 peerDependencies에는 react가 포함됩니다.)

 

4. 스크립트 실행

• scripts: 프로젝트에서 사용할 명령어들을 모아놓은 객체 pnpm run <스크립트명> 형태로 실행

 

5. 패키지 진입점 및 모듈 시스템 (라이브러리 개발 시 중요)

 

1. 내부 설계 및 개발 (type 필드의 역할)

• type: 프로젝트 내부의 js 파일들을 기본적으로 CommonJS로 처리할지, ESM으로 처리할지 결정
• files: npm에 패키지를 배포할 때 포함될 파일 및 폴더 목록을 지정 (예: ["dist", "README.md"])

 

 

2. 외부 진입점 역할

 

구형:

• main: CommonJS 환경(require())에서 패키지를 불러올 때의 진입점 파일입니다.
• module: ESM(import) 환경에서 패키지를 불러올 때의 진입점 파일입니다. 번들러가 더 효율적으로 처리할 수 있습니다.
• types (또는 typings): TypeScript 타입 선언 파일(.d.ts)의 위치를 지정합니다.

 

신형:

• exports: main, module보다 더 현대적이고 강력한 진입점 설정 방식입니다. 특정 파일만 외부로 노출시키는 등 세밀한 제어가 가능합니다.

 

 

 

 

🖌️ 누가 이 정보를 사용하나요?

package.json에 작성한 내용은, 다양한 개발 도구들이 이 정보를 읽고 활용함

 

1. 번들러(Bundler)와 Node.js 런타임

• 언제?: 다른 프로젝트에서 import { formatDate } from '@my-repo/utils'; 와 같은 코드를 만났을 때
• 어떻게?:
  1. 번들러(Vite, Webpack 등)나 Node.js는 @my-repo/utils 패키지의 package.json 파일을 열어봅니다.
  2. 현재 환경이 ESM을 지원하면 module 필드에 적힌 경로(예: ./dist/index.js)를 찾아가고, 그렇지 않으면 main 필드의 경로를 찾아갑니다.
  3. 해당 경로의 파일을 읽어 formatDate 함수를 가져옵니다.
• 요약: 즉, 이 필드들은 import 구문이 어떤 파일을 찾아가야 하는지에 대한 이정표 역할을 합니다.

 

 

🔍 알아두기

 

번들러 vs Node.js  핵심 차이

역할	소스코드를 번들링(변환)	JavaScript 실행 환경 (런타임)
언제 실행됨?	빌드 타임	런타임
목적	코드 압축, 트랜스파일, 모듈 병합	JS 코드 실행, 서버 구성
입력	.js, .ts, .css 등 소스 파일들	이미 번들되었거나 실행 가능한 JS 파일
출력	실행 가능한 번들 파일 (bundle.js)	실행 결과 (예: 서버 동작, API 응답)
대표 도구	Webpack, Vite, esbuild, Rollup	Node.js 자체

런타임 = 실행환경

 

2. 타입스크립트 컴파일러 (TypeScript Compiler)

• 언제?: 타입스크립트 프로젝트에서 @my-repo/utils를 사용할 때
• 어떻게?:
  1. 타입스크립트 컴파일러(tsc)는 @my-repo/utils의 package.json을 열어 types 필드를 확인합니다.
  2. types 필드에 적힌 경로(예: ./dist/index.d.ts)의 타입 선언 파일을 읽습니다.
  3. formatDate 함수의 매개변수가 Date 타입이고 반환값이 string 타입이라는 것을 인지하여, 코드 자동완성(IntelliSense)과 타입 체크를 제공합니다.