package.json

package.json은 npm 패키지의 정보와 의존성, 실행 스크립트 등을 JSON 형식으로 선언하는 파일입니다. 파일에 적힌 선언과 실제 설치된 패키지는 구분됩니다. 프로젝트에서 어떤 명령을 제공하고 어떤 패키지를 필요로 하는지 읽는 출발점이며, 설치 결과를 고정하는 잠금 파일과 JavaScript를 실행하는 런타임은 별도 역할을 맡습니다.

패키지 정보와 의존성 선언

npm의 package.json 참조 문서는 이 파일에 들어가는 필드를 설명합니다. name은 패키지 이름, version은 버전 정보를 담습니다. description과 저장소 정보처럼 사람이나 도구가 패키지를 이해하는 데 쓰는 항목도 있습니다. 파일은 유효한 JSON이어야 하므로, JavaScript 객체 리터럴처럼 임의의 주석이나 실행식을 넣는 방식과는 구분됩니다.

dependencies는 패키지 이름과 필요한 버전 범위 등을 연결합니다. devDependencies에는 개발과 검사에 필요한 패키지를 선언합니다. 두 필드는 프로젝트에서 맡는 역할을 구분하지만, 실제 설치 항목은 설치 명령과 옵션의 영향도 받습니다. 개발 의존성이라고 적혔다는 사실만으로 모든 실행 환경에서 자동으로 제외되지는 않습니다. 배포 과정이 어떤 방식으로 설치하는지 함께 읽으면 누락된 도구의 원인을 찾기 쉽습니다.

버전 선언은 정확한 한 버전일 수도 있고 여러 버전을 허용하는 범위일 수도 있습니다. 같은 선언을 유지한 채 다른 시점에 의존성을 해결하면 선택되는 버전이 달라질 여지가 있습니다. 프로젝트의 파일에 패키지 이름이 있다고 이미 설치되어 있는 것도 아닙니다. 선언 파일, 설치된 디렉터리, 설치 도구가 기록한 결과는 각각 무엇을 요구했고 무엇이 준비됐는지 보여 주는 다른 자료입니다.

scripts가 정하는 프로젝트 명령

npm의 스크립트 문서는 scripts 속성에 명령 이름과 실행 내용을 연결하는 방법을 설명합니다. npm run build를 실행할 때 실제로 무엇을 수행할지는 build 항목에 적힌 명령이 정합니다. 이름이 같아도 프로젝트에 따라 코드 변환, 타입 검사, 파일 복사 등 포함 단계가 달라집니다. 명령 이름만으로 검사 범위를 확정할 수는 없습니다.

pre와 post를 붙인 대응 스크립트는 본 스크립트의 앞뒤에 실행될 수 있습니다. prebuild, build, postbuild를 함께 정의했다면 가운데 명령만 읽어서는 전체 실행 내용을 놓칩니다. 설치 과정에도 별도의 생명주기 스크립트가 연결될 수 있습니다. 의존성을 설치하거나 프로젝트 명령을 실행하기 전에 어떤 코드가 이어지는지 확인하면, 단순 파일 읽기와 프로그램 실행을 구별할 수 있습니다.

개발자가 원하는 명령 이름이 파일에 없으면 그 이름으로 실행할 작업도 정의되지 않은 상태입니다. 다른 프로젝트에서 사용하던 npm run dev를 그대로 옮겼을 때 실패하는 이유가 여기에 있을 수 있습니다. 실행 위치 역시 해당 파일을 찾는 데 영향을 줍니다. 저장소에 여러 패키지가 있다면 루트의 설정과 하위 패키지의 설정 중 어느 쪽 명령을 실행했는지 기록합니다.

잠금 파일과 실행 환경의 경계

package-lock.json은 설치된 의존성 트리를 재현할 수 있도록 npm이 기록하는 잠금 파일입니다. package.json의 버전 요구와 실제 해결 결과를 같은 정보로 읽으면 설치 재현성을 오해하게 됩니다. 패키지를 바꾸는 작업에서는 선언과 잠금 파일의 변경이 함께 나타날 수 있습니다. 한쪽만 수정한 뒤 다른 쪽에 이전 결과를 남기면 설치 방식에 따라 오류나 예상하지 못한 차이가 생깁니다.

engines 필드는 패키지가 요구하는 Node.js나 npm 버전 범위를 표시하는 데 쓰입니다. npm 문서는 이 필드가 기본적으로 권고 성격이며 설정에 따라 처리 강도가 달라진다고 설명합니다. 요구 버전을 적어 두는 일과 그 버전의 실행 파일을 실제로 설치하는 일은 다릅니다. 명령이 시작되더라도 대상 버전에서 필요한 API를 지원하는지는 실행 환경과 함께 확인합니다.

2026년 10월 11일 확인한 npm 11 문서를 기준으로 필드의 역할을 설명했습니다. 다른 패키지 관리자는 같은 파일을 읽더라도 자신의 설정과 잠금 파일 규칙을 사용합니다. 오류를 비교할 때는 package.json 내용뿐 아니라 사용한 도구, 실행 위치, 버전, 설치 옵션을 남깁니다. 같은 저장소의 같은 파일을 보았다는 조건만으로 설치된 환경까지 같다고 판단하지 않습니다.