package.json

모든 JavaScript 또는 TypeScript 프로젝트의 루트에는 package.json이 있어요. 패키지 매니저가 읽어서 무엇을 설치할지, 어떤 스크립트를 실행할지, 프로젝트 버전이 어떻게 되는지 파악하는 파일이에요.

package.json 생성하기

가장 빠른 시작 방법:

$npm init -y

또는 pnpm으로:

$pnpm init

-y 플래그는 모든 질문에 "예"로 답해요. 손으로 편집할 수 있는 최소한의 파일이 생성돼요.

전체 예시 (주석 포함)

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "프로젝트 간단 설명",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest"
  },
  "dependencies": {
    "react": "^18.3.0",
    "react-dom": "^18.3.0"
  },
  "devDependencies": {
    "vite": "^5.2.0",
    "vitest": "^1.6.0",
    "@types/react": "^18.3.0"
  },
  "engines": {
    "node": ">=20.0.0"
  }
}

핵심 필드

name : 프로젝트의 고유 식별자(소문자, 공백 없음). npm에 게시할 경우 필수예요.

version : semver 형식의 버전 번호(MAJOR.MINOR.PATCH). 게시된 프로젝트는 1.0.0으로 시작하고, 진행 중인 프로젝트는 0.1.0으로 시작해요.

type : "module"은 import/export(ESM)을 사용하고, 없거나 "commonjs"이면 require()를 사용해요. 2026년에는 "module"이 표준이에요.

scripts : pnpm run <이름>으로 실행하는 명령어들이에요. 자주 쓰는 이름 : dev, build, test, start, lint.

dependencies : 프로덕션에서 필요한 패키지들(런타임).

devDependencies : 개발 중에만 사용하는 패키지들(컴파일러, 린터, 테스트). 최종 빌드에 포함되지 않아요.

engines : 필요한 최소 Node 버전. 오래된 버전의 머신에서 생기는 문제를 예방해요.

peerDependencies

네 번째 의존성 타입인 peerDependencies도 있어요. 라이브러리를 개발할 때 사용하는데, 호스트 애플리케이션이 이미 특정 패키지를 설치했다고 가정해요(예 : React 18이 필요한 React 플러그인). 라이브러리 사용자가 직접 이 peer 패키지를 설치해야 해요.

package.json 직접 편집하기

package.json을 직접 편집하는 것은 완전히 일반적이에요. "lint": "eslint ." 스크립트를 추가하거나, type을 변경하거나, 버전을 조정해요. 변경 후에는 pnpm install을 실행해서 lockfile을 재동기화하세요.