[npm] package-lock.json이 필요한 이유

npm을 사용한다면 무조건 보게 되는 파일이 있다. 바로 package-lock.json 이다. package.json 에 명시된 의존성 패키지들의 히스토리를 관리해주는 파일 정도로만 인지하고 있었는데, 점점 프로젝트의 복잡도가 높아지면서 package.json을 통해 패키지를 설치하더라도 환경에 따라 빌드 또는 실행이 안 되는 문제가 종종 발생하게 되었다. 패키지 버전을 수정하지 않았는데도 다른 개발자와 package-lock.json 에서 코드 충돌이 나는 경우도 발생했다. 왜 package.json 만으로 의존성 관리가 되지 않는 것일까?

package.json의 한계

규모가 큰 프로젝트의 경우, 여러 명의 개발자들이 동일한 개발 환경을 가지는 것이 중요하다. 이때, package.json만으로는 부족할 때가 있다. npm 모듈의 semantic versioning(semver) 기반 범위 지정 방식 때문이다. semver 에서는 [Major].[Minor].[Patch] 와 같은 방식으로 버저닝이 구성된다. 이때, 버전 정보 앞에 기호를 부여하여 업데이트 범위를 지정할 수 있는데, 기술 방식은 다음과 같다. 

표기법	Description
version	명시된 version과 일치
>version	명시된 version보다 높은 버전
>=version	명시된 version과 같거나 높은 버전
<version	명시된 version보다 낮은 버전
<=version	명시된 version과 같거나 낮은 버전
~version	명시된 version과 근사한(?) 버전. 패치 버전 범위 내에서 업데이트한다.  ex) ~0.0.1: 0.0.1 ≤ version < 0.1.0 ex) ~0.1.1: 0.1.1 ≤ version < 0.2.0
^version	명시된 version과 호환되는 버전. 마이너 버전 범위 내에서 업데이트한다. ex) ^1.0.2: 1.0.2 ≤ version < 2.0

따라서 A 패키지에 대해 ^1.2.3 이라고 package.json에 설정해 둔다면, 내 로컬에는 실제로 1.2.4가 설치될 수도 있고 1.3이 설치될 수도 있게 된다. 그렇다면 여러 명의 개발자가 협업할 때, 또는 배포 환경에 실제로 배포가 될 때 설치되는 버전을 명확하게 알 수 없는 문제가 있다. 나와 내 동료가 같은 버전을 사용한다는 보장이 없게 되는 것이다. 유동적인 상황이 발생하는 과정에서도 개발 환경에서 발생하는 의존성 버전 정보를 고정시키기 위해 필요한 것이 바로 package-lock.json이다. 

package-lock.json이란

package-lock.json은 npm 패키지 매니저에서 node_modules 디렉토리에 설치된 패키지들의 의존성 트리를 기록하는 파일을 말한다. npm을 사용해서 node_modules 트리나 package.json 파일을 수정하게 되면 자동으로 생성되는데, 이 파일은 파일 생성 시점의 의존성 트리에 대한 정보를 가지게 된다. 따라서 package.json의 버전 범위에 따라 버전이 바뀌더라도, package-lock.json 파일이 작성된 시점의 의존성 트리가 다시 생성될 수 있게끔 보장할 수 있게 되는 것이다.

다음과 같은 package.json이 있다고 하자.

{
  "name": "my-app",
  "version": "0.1.0",
  "dependencies": {
    "@apollo/client": "^3.7.10",
		... 
  }
}

해당 package.json 파일로 npm install을 실행하면 현재는 3.7.10 버전이 설치될 것이다. (apollo/client의 가장 최근 릴리즈) 그러나 apollo/client의 새로운 minor, patch가 릴리즈될 경우 동일한 package.json 파일로 npm install을 실행해도 3.8.0이나 3.7.11과 같은 업데이트된 버전이 설치될 것이다. package-lock.json 파일을 소스 저장소에 커밋하지 않은 경우, 다른 환경 및 시점에 npm install을 할 경우 코드 실행 시 예기치 못한 오류가 발생할 수 있다. 그러나 package-lock.json을 저장소에 커밋하고 동료 개발자들과 함께 참조하도록 사용할 경우, 의존성 트리가 어떤 실행 환경에서도 동일하게 설치될 것이다.

npm 패키지 매니저 버전 5부터는 package-lock.json 파일이 자동으로 생성되며, npm 패키지 매니저 버전 6부터는 이 파일이 필수 파일로 취급된다. 따라서 npm을 사용하는 프로젝트에서는 package-lock.json 파일을 함께 관리하는 것이 좋다.

결론

package-lock.json은 반드시 커밋하자. 프로젝트의 복잡도가 높아지고 더 많은 개발자와 협업하게 될 수록 package-lock.json 관리는 필수다. (node_modules를 저장소에 커밋하지 않는 이상 말이다!)

Reference

• https://github.com/npm/node-semver#versions
• https://poiemaweb.com/nodejs-npm