npm과 package.json: 남이 만든 도구 가져다 쓰기

01. Node.js와 npm 설치

npm(Node Package Manager)은 자바스크립트 패키지를 내려받고 관리하는 도구예요. Node.js를 설치하면 함께 들어 있어요. nodejs.org에서 LTS(장기 지원) 표시가 붙은 버전을 고르면 돼요. 2026년 11월 기준 최신 LTS는 2026년 10월 28일에 LTS가 된 Node.js 26이에요.

설치한 뒤 터미널에서 버전이 나오는지 확인해요.

node -v     # Node.js 버전
npm -v      # npm 버전

패키지는 npm 레지스트리(npmjs.com)라는 공개 저장소에 올라가 있어요. 누구나 올릴 수 있어서 수백만 개가 있는 만큼, 무엇을 설치할지는 신중하게 골라야 해요(팀에서 같이 쓰기).

02. package.json: 프로젝트 설명서

프로젝트 폴더에서 npm init -y를 실행하면 package.json이 생겨요. 프로젝트 이름, 쓰는 패키지 목록, 자주 쓰는 명령을 적어 두는 파일이에요. 패키지를 설치하면 npm이 이 파일을 알아서 고쳐요.

{
  "name": "todo-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "lint": "eslint .",
    "format": "prettier . --write",
    "test": "vitest"
  },
  "dependencies": {
    "date-fns": "^4.1.0"
  },
  "devDependencies": {
    "eslint": "^10.14.0",
    "prettier": "3.9.10",
    "vitest": "^5.1.0"
  }
}

• "type": "module": Node.js에서 이 폴더의 .js 파일을 모듈(import · export, 13장)로 읽게 해요. npm init -y로 만들면 이 줄이 "commonjs"로 들어가요(npm 11 기준). import를 쓰려면 직접 "module"로 고치거나 npm pkg set type=module을 실행해요. Vite 같은 도구로 만든 프로젝트에는 처음부터 "module"이 들어 있어요.
• scripts: 긴 명령에 짧은 이름을 붙여 둬요. 아래 npm run에서 다뤄요.
• dependencies · devDependencies: 설치한 패키지와 허용하는 버전 범위예요(위 숫자는 예시예요).

03. 패키지 설치: dependencies와 devDependencies

패키지는 쓰임에 따라 두 곳으로 나눠 설치해요.

설치하면 두 가지가 생겨요. node_modules 폴더에는 패키지 파일이 실제로 들어가요. 패키지가 또 다른 패키지를 쓰기 때문에 금방 커지지만, 언제든 npm install로 다시 만들 수 있어서 저장소(git)에 올리지 않아요. package-lock.json에는 실제로 설치한 정확한 버전이 전부 기록돼요.

버전 범위 읽기

버전은 주.부.수(예: 4.1.0) 세 숫자예요. 앞 숫자가 바뀌면 기존 코드가 깨질 수 있는 큰 변경, 가운데는 기능 추가, 끝은 버그 수정이라는 약속(시맨틱 버저닝)을 따라요. package.json의 기호는 허용 범위예요.

• ^4.1.0: 4.1.0 이상, 5.0.0 미만 — 앞 숫자가 같은 범위에서 최신 (npm의 기본)
• ~4.1.0: 4.1.0 이상, 4.2.0 미만 — 버그 수정만
• 4.1.0: 정확히 그 버전만

범위가 있으니 사람마다 다른 버전이 설치될 수 있잖아요? 그걸 막는 게 package-lock.json이에요. lock 파일이 있으면 npm install은 거기 적힌 버전을 그대로 써요.

04. npm run과 npx

scripts에 적은 명령은 npm run 이름으로 실행해요. 팀원 모두가 같은 명령을 쓰게 되고, 도구의 긴 옵션을 외울 필요가 없어요. test · start는 자주 써서 run을 빼도 돼요.

npm run lint     # eslint . 실행
npm run format   # prettier . --write 실행
npm test         # vitest 실행 (npm run test와 같아요)

npx 도구이름은 프로젝트에 설치된 도구를 바로 실행해요(npx eslint app.js). 설치되지 않은 도구라면 잠시 내려받아 한 번 실행해요. 프로젝트를 만드는 생성기(npm init @eslint/config@latest, npm create vite@latest)도 같은 방식으로 동작해요.

05. 팀에서 같이 쓰기

• 무엇을 저장소에 올리나요? package.json과 package-lock.json은 올리고, node_modules는 .gitignore에 넣어 올리지 않아요.
• 자동 빌드 · 배포 서버(CI)에서는 npm ci를 써요. lock 파일과 정확히 같은 버전만 깨끗하게 설치하고, package.json과 lock 파일이 어긋나면 멈춰서 알려 줘요.
• 설치 전에 확인해요. 내려받는 수, 최근 업데이트, 관리하는 사람을 보고, 이름이 비슷한 가짜 패키지(오타를 노린 이름)를 조심해요. 패키지는 설치할 때 스크립트를 실행할 수도 있어요.
• 알려진 보안 문제는 npm audit으로 확인할 수 있어요. 버전을 올릴 때는 npm outdated로 무엇이 뒤처졌는지 보고, 큰 변경(앞 숫자)은 변경 기록을 읽고 올려요.
• 작은 일에는 패키지를 들이지 않아요. 몇 줄로 쓸 수 있는 기능까지 패키지로 해결하면, 관리할 것과 보안 위험이 함께 늘어요. 자바스크립트에 이미 있는 기능(5장의 배열 · 날짜 기능 등)으로 되는지 먼저 확인해요.