TypeScript에서 global.d.ts의 역할과 배포 전략

TypeScript로 프로젝트를 하다 보면 global.d.ts라는 파일을 마주치게 된다.

처음에는 단순히 “글로벌 타입 정의 넣는 곳” 정도로만 이해하고 사용하게 되는데...

 

실제로 사용하다보면 빌드 과정과 npm 배포 시 주의해야 할 점이 있다.

 

이번 글에서는 global.d.ts를 사용하면서 마주치는 이슈들에 대해서 정리해보기로 했다.

1. global.d.ts는 어떤 역할을 하는가
2. 빌드시 어떻게 처리되는가
3. npm publish 시 포함 전략

1. global.d.ts란 무엇인가

TypeScript에서 *.d.ts 파일은 타입 선언 파일(Declaration File)이다.

그 중 global.d.ts는 이름처럼 전역 타입을 선언하는 곳으로 쓰이는 파일이다.

 

예를 들어, window 객체에 커스텀 프로퍼티를 추가한다고 해보자 (가장 만만한 글로벌 타입)

// global.d.ts
export {};

declare global {
  interface Window {
    myAppVersion: string;
  }
}

이렇게 작성하면 프로젝트 전체에서 window.myAppVersion을 타입 에러 없이 사용할 수 있다.

 

2. global.d.ts는 빌드시 어떻게 처리되는가 🍉

여기서 중요한 점은 다음과 같은 사실이다 🍕

• *.d.ts 파일은 실제 JS로 빌드되지 않는다
• 대신 타입스크립트 컴파일러(tsc)가 타입 정보로만 활용한다

즉, global.d.ts 안의 코드는 빌드 결과물에 포함되지 않으며, 오직 타입 체킹용으로만 쓰이게 된다.
(실행 시점에는 아무런 영향을 주지 않는다)

 

include 설정 확인

tsconfig.json에서 include 경로나 files 옵션에 global.d.ts가 잡혀 있어야만 프로젝트에 반영된다.

{
  "compilerOptions": {
    "strict": true
  },
  "include": ["src", "global.d.ts"]
}

만약 여기서 누락되면 빌드 시 타입 선언이 무시될 수 있다.

 

3. npm publish 시 global.d.ts 포함 전략

global.d.ts가 포함된 프로젝트 라이브러리를 npm에 배포할 때도 주의할 점이 있다.
보통 라이브러리 사용자도 동일한 글로벌 타입을 인식해야 하므로, global.d.ts를 패키지에 함께 배포해야 한다!!

그렇담, 어떻게 포함시킬 수 있을까?

 

방법 1. files에 global type 포함 시키기

{
  "name": "my-lib",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist", "global.d.ts"]
}

여기서 "files" 배열에 global.d.ts를 꼭 추가해야 npm publish 시 패키지에 포함된다.

• types: 소비자가 import 시 자동으로 참조할 타입 정의 파일을 지정한다.
• files: npm 배포 시 포함될 파일 목록. 여기서 global.d.ts를 직접 넣어주면 함께 배포된다

++  typesVersions 속성 예제

공식문서를 보다가 알게된 내용인데, 처음 봐서 추가로 기록해두기로 했다 🍎

TypeScript 버전에 따라 다른 타입 정의를 제공할 때 쓴다.
예를 들어, TS 4.5 이상에서는 새로운 타입을 제공하고, 그 아래 버전에서는 구 버전을 제공할 수 있다.

{
  "name": "my-lib",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist",
    "global.d.ts"
  ],
  "typesVersions": {
    ">=4.5": {
      "*": [
        "dist/types/ts4.5/*"
      ]
    },
    "*": {
      "*": [
        "dist/types/legacy/*"
      ]
    }
  }
}

• TS 4.5 이상을 쓰는 소비자는 dist/types/ts4.5 경로의 타입 정의를 사용
• 그 외 TS 버전은 dist/types/legacy 경로를 사용

즉,

• 간단히 하나만 지정할 땐 "types"
• 버전에 따라 다르게 제공하려면 "typesVersions"

 

방법 2. index.d.ts에서 import

global.d.ts를 별도 파일로 두되, 메인 타입 선언 파일에서 명시적으로 가져오는 방식이다.

// index.d.ts
/// <reference path="./global.d.ts" />

이러면 types 엔트리포인트 하나만 지정해도 글로벌 선언이 따라오게 된다.

 

4. 언제 global.d.ts를 쓰는 게 맞을까? 🧐

• 프로젝트 내부 전용이라면

-> 그냥 src/types 폴더 아래 두고 tsconfig에 include 시키면 충분

• 배포하는 라이브러리라면

-> 소비자가 자동으로 타입을 인식할 수 있도록 files와 types 설정을 꼼꼼히 챙겨야 함

 

 

&&& 

• global.d.ts는 타입 선언용이므로 빌드 산출물(JS)에는 포함되지 않는다.
• tsconfig에 include를 꼭 확인해야 한다.
• npm 배포 시에는 files에 global.d.ts를 포함하거나 index.d.ts에서 참조하도록 전략을 세워야 한다.

 

 

참고 자료 📏

• TypeScript Handbook - Declaration Files
• DefinitelyTyped 가이드
• npm docs - files
• typesVersion 문서