초보 개발자를 위한 package.json 구성요소 쉽게 이해하기

초보 개발자를 위한 package.json 구성요소 쉽게 이해하기

Node.js 또는 프론트엔드 개발을 시작하면 가장 먼저 마주치는 파일이 package.json입니다. 처음에는 자동으로 생기는 파일처럼 느껴질 수 있지만, 사실 이 파일은 프로젝트의 핵심 정보를 담고 있는 매우 중요한 설정 파일입니다.

 

package.json이란?

package.json은 현재 프로젝트에 어떤 패키지가 설치되어 있는지, 어떤 이름을 가지고 있는지, 어떤 명령어로 실행되는지를 정의한 파일입니다. 한마디로, Node.js 프로젝트의 설명서라고 할 수 있습니다.

 

자주 사용하는 항목 설명

1. name & version

"name": "my-app",
"version": "1.0.0"

• name: 프로젝트 이름입니다. 패키지로 배포할 경우 고유해야 합니다.
• version: 현재 프로젝트의 버전이며, 보통 주.부.수 형식(SemVer)을 따릅니다.

2. description & keywords

"description": "간단한 예제 프로젝트입니다.",
"keywords": ["nodejs", "example", "starter"]

• description: 프로젝트에 대한 간단한 설명입니다.
• keywords: npm 검색 시 노출을 돕기 위한 키워드 목록입니다.

3. main

"main": "index.js"

외부에서 이 패키지를 require() 또는 import할 경우 기본적으로 불러올 파일 경로를 지정합니다.

4. scripts

"scripts": {
  "start": "node index.js",
  "dev": "nodemon index.js"
}

자주 사용하는 명령어를 단축해서 실행할 수 있도록 정의하는 항목입니다. 예를 들어, npm run dev처럼 사용할 수 있습니다.

5. dependencies & devDependencies

"dependencies": {
  "express": "^4.18.2"
},
"devDependencies": {
  "nodemon": "^2.0.22"
}

• dependencies: 실제 동작에 필요한 패키지를 지정합니다.
• devDependencies: 개발 중에만 필요한 도구를 지정합니다.

6. license, author, repository

"license": "MIT",
"author": "홍길동 <hong@example.com>",
"repository": {
  "type": "git",
  "url": "https://github.com/hong/my-app"
}

해당 프로젝트가 어떤 라이선스를 따르는지, 누가 만들었는지, 깃 저장소 주소가 무엇인지 등의 메타정보를 담고 있습니다.

7. private

"private": true

실수로 npm에 업로드되는 것을 방지하고자 할 때 사용하는 옵션입니다.

 

package-lock.json이란?

 

package-lock.json은 설치된 패키지의 정확한 버전과 경로를 기록한 파일입니다. package.json에만 의존할 경우 팀원마다 설치되는 버전이 달라질 수 있기 때문에, package-lock.json을 통해 동일한 개발 환경을 유지할 수 있습니다.

주요 역할

• 의존성 버전 고정
• 하위 모듈까지 정확한 버전 기록
• 재설치 시 빠른 성능과 동일한 환경 보장

주의할 점

• package-lock.json은 직접 수정하지 않고, npm install을 통해 자동으로 관리합니다.
• 협업 시 package.json과 함께 반드시 커밋해야 합니다.

package.json과 package-lock.json 비교

항목	package.json	package-lock.json
역할	필요한 패키지 선언	정확한 버전 기록
작성 방법	직접 수정	npm이 자동 생성
버전 지정	범위 지정 (^, ~)	고정된 정확한 버전
커밋 여부	필수	필수

예시 package.json

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "Node.js 입문용 예제입니다.",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "nodemon": "^2.0.22"
  },
  "author": "홍길동",
  "license": "MIT"
}

 

마치며

package.json과 package-lock.json은 단순한 설정 파일을 넘어, 프로젝트의 뼈대를 구성하고 일관된 개발 환경을 유지하게 해주는 핵심 요소입니다. 이 두 파일을 정확히 이해하고 관리하는 것은 안정적이고 효율적인 개발을 위한 첫걸음이죠.

스마트베이는 이러한 개발의 기본기를 중요하게 생각하며, 작은 차이가 큰 품질을 만든다고 믿습니다. 앞으로 코드를 작성할 때 이 작은 파일들이 해내는 역할을 한 번 더 떠올려보세요.

개발은 디테일에서 시작됩니다.

 

---

스마트베이 | IT 자동화 혁신 파트너
비즈니스 효율을 높이는 스마트한 IT 솔루션을 제공합니다.

웹사이트 : www.esmartbay.co.kr
E-mail : smartbay.svc@gmail.com
카카오톡 : 바로 상담하기