Rae.

package.json의 버전 관리 이해하기

2025-09-07

1. 개요

이 글에서는 npm에서 설치하는 라이브러리나 프레임워크 등의 패키지 버전이 Semantic Versioning을 통해 어떤식으로 관리되는지에 대해 설명합니다.

2. Semantic Versioning

Sementic Versioning(SemVer)이란 x.y.z라는 3개의 숫자 구성 요소를 통해 패키지의 버전을 관리하는 체계입니다. x, y, z는 각각 Major, Minor, Patch 버전이라고 하며, 각 버전이 변경되는 경우를 요약하자면 다음과 같습니다.

  • Major: 기존 버전과 호환되지 않게 API가 바뀌는 경우
  • Minor: 기존 버전과 호환되면서 새로운 기능을 추가한 경우
  • Patch: 기존 버전과 호환되면서 버그를 수정한 경우

여기서 API(public API)는 사용자가 소프트웨어에 접근할 수 있는 '공식적인 접근 지점'을 가리킵니다. 라이브러리의 경우 라이브러리 외부에서 호출할 수 있는 메서드, 함수 시그니처, 그리고 노출된 엔트리포인트 전체 집합 등이 API에 해당합니다. 웹 프론트엔드 개발에서 널리 사용되는 라이브러리인 React의 경우 useState, useEffect등이 대표적인 public API라고 볼 수 있습니다.

아래에서 React를 예시로 Major, Minor, Patch에 대해 좀 더 세부적으로 알아보겠습니다.

2.1. Patch

Patch 버전의 경우, 기존 버전의 API와 하위 호환성을 유지한 채 변화를 주지 않는 범위 내에서의 발견된 버그나 오류를 수정할 때 업데이트가 발생합니다.

React의 Patch 버전 업데이트 사례로는 17.0.0 → 17.0.1 로의 변경이 있습니다. 이때 특정 상황, 예컨대 Internet Explorer 11 환경에서 발생하던 크래시 오류가 수정되어, 기능적인 변화 없이 버그만 해결됨으로써 안정성이 향상되었습니다

2.2. Minor

Minor 버전의 경우, 기존 버전의 API와 하위 호환성을 유지하면서(backward-compatible) 새로운 기능이 추가되었을 때 업데이트가 발생합니다.

React의 Minor 버전 업데이트 사례로는 16.7.0 → 16.8.0으로의 변경이 있습니다. 이때 useState, useEffect와 같은 Hook 기능들이 새롭게 도입되어, React 개발자들이 클래스 컴포넌트 이외에도 Hook을 통해 상태 관리와 생명주기 기능을 함수형 컴포넌트 내에서 사용할 수 있게 되었습니다.

2.3. Major

Major 버전의 경우, 기존 버전의 API와 하위 호환성이 보장되지 않는(not backward-compatible) API의 변경이 일어났을 때 업데이트가 발생합니다. 기존의 API를 아예 삭제했거나 그 이름을 바꾸는 등의 변화가 이에 해당합니다.

React의 Major 버전 업데이트 사례로는 17.0.2 → 18.0.0 으로의 변경이 있습니다. 이 과정에서 기존 애플리케이션 진입점에서 사용되던 ReactDOM.render() API가 제거되고, 새로운 방식인 createRoot() API로 대체되면서 이전 버전과의 호환성이 깨지는 변경 사항이 발생했습니다.

3. SemVer Ranges

버전 앞에 붙는 ^(caret)이나 ~(tilde) 기호는 npm이 패키지를 설치할 때 허용할 버전의 범위를 지정하는 규칙입니다.

3.1. ~(tilde)

~의 경우, 패키지를 Minor 버전을 유지하는 범위 내에서 Patch 버전을 최신으로 업데이트합니다.

여러분이 현재 사용하고 있는 패키지가 1.2.3 버전이고 버전 앞에 ~를 붙인다면 1.2.3부터 1.3.0 이전까지, 즉 1.2.z 범위의 최신 버전 업데이트를 허용하게 됩니다.

~1.2.3:=>=1.2.3 <1.(2+1).0:=>=1.2.3 <1.3.0

3.2. ^(caret)

^의 경우, 패키지를 Major 버전을 유지하는 범위 내에서 Patch 버전을 포함한 Minor 버전을 최신으로 업데이트합니다.

여러분이 현재 사용하고 있는 패키지가 1.4.2 버전이고 버전 앞에 ^를 붙인다면 1.2.3부터 2.0.0 이전까지, 즉 1.y.z 범위의 최신 버전 업데이트를 허용하게 됩니다.

^1.2.3:=>=1.2.3 <2.0.0