@types/node 버전 어디에 맞춰야 함?

1.  

최근 Node 버전을 업데이트하다가 @types/node 버전이 어떻게 관리되는지 궁금해져서 찾아보게 되었습니다.

핵심 내용은 DefinitelyTyped 저장소의 문서에 정리되어 있습니다.

👉
https://github.com/DefinitelyTyped/DefinitelyTyped?tab=readme-ov-file#how-do-definitely-typed-package-versions-relate-to-versions-of-the-corresponding-library

해당 내용을 정리하고 번역해 보았습니다.

---

1. 기본 전제: Semantic Versioning

문서에서는 다음 내용을 전제로 설명합니다.

NOTE: The discussion in this section assumes familiarity with Semantic versioning

 

즉, Semantic Versioning(시맨틱 버저닝)에 대한 이해가 필요합니다.

일반적으로 라이브러리 버전은 다음과 같은 구조를 가집니다.

major.minor.patch

예

20.8.1

• major : 큰 변경 (breaking change)
• minor : 기능 추가
• patch : 버그 수정

---

2. DefinitelyTyped 패키지는 어떻게 버전이 정해질까?

각 DefinitelyTyped 패키지는 npm에 배포될 때 버전이 지정됩니다.

Each Definitely Typed package is versioned when published to npm.

 

@types 패키지를 npm에 배포하는 도구인 DefinitelyTyped-tools는
package.json에 있는 major.minor.9999 형식의 버전을 기준으로 타입 패키지 버전을 설정합니다.

예를 들어 @types/node의 package.json은 다음과 같이 되어 있습니다.

{
  "private": true,
  "name": "@types/node",
  "version": "20.8.9999"
}

이 경우 npm에 배포되는 @types/node의 버전은

20.8.x

형태로 관리됩니다.

---

3. 왜 .9999를 사용할까?

문서에 따르면 .9999를 사용하는 이유는 다음과 같습니다.

(.9999 is to ensure that local @types packages are always newest during local development.)

 

즉,

로컬 개발 환경에서 항상 최신 버전으로 인식되도록 하기 위함

입니다.

또한 중요한 점이 하나 있습니다.

라이브러리와 타입 패키지는 major와 minor 버전만 맞춥니다.

라이브러리
20.8.1

타입 패키지
20.8.x

패치 버전은 서로 맞출 필요가 없습니다.

---

4. 타입 패키지의 patch 버전은 어떻게 증가할까?

타입 선언 패키지의 patch 버전은 다음 규칙을 따릅니다.

20.8.0
20.8.1
20.8.2

이 숫자는

라이브러리 patch 버전과 무관합니다

대신 다음 기준으로 증가합니다.

같은 major/minor 버전에서 타입 선언이 업데이트될 때마다 증가

node 20.8.x

 

@types/node
20.8.0
20.8.1
20.8.2

---

5. 라이브러리와 타입 버전이 어긋나는 이유

문서에서도 설명하듯이
라이브러리 버전과 타입 버전이 항상 완벽하게 일치하지는 않습니다.

대표적인 이유는 다음과 같습니다.

1️⃣ patch 버전은 원래 다름

타입 패키지 patch는

타입 수정 횟수

기준입니다.

 

그래서

라이브러리 patch ≠ 타입 patch

입니다.

---

2️⃣ 새로운 기능이 추가된 경우

새로운 기능이 추가되면 타입 선언도 업데이트되어야 합니다.

이때 반드시 major.minor 버전을 라이브러리와 맞춰야 합니다.

---

3️⃣ 커뮤니티 기반 업데이트

DefinitelyTyped는 대부분 커뮤니티 기여로 유지됩니다.

그래서

라이브러리 업데이트
→ 타입 업데이트 지연

이 자주 발생합니다.

문서에서도 다음과 같이 설명합니다.

타입 선언 패키지 업데이트는 며칠, 몇 주, 심하면 몇 달 늦어질 수 있습니다.

 

이 경우 직접 PR을 보내 기여할 수도 있습니다.

---

6. 정리

DefinitelyTyped 버전 규칙

1️⃣ package.json 

major.minor.9999

 

2️⃣ npm 배포

major.minor.x

 

 

3️⃣ patch 버전

타입 수정 횟수 기준 증가

 

4️⃣ 라이브러리와 맞춰야 하는 것

major
minor

---

결론

결국 개발자가 신경 써야 하는 것은 다음입니다.

라이브러리 major/minor
=
@types major/minor

그리고

patch는 최신 버전 사용

즉 실무적으로는 이렇게 이해하면 됩니다.