선언 파일(.d.ts) — JavaScript 라이브러리에 타입 입히기

npm에서 패키지를 설치하면 TypeScript가 그 패키지의 타입을 알아서 파악해주면 좋겠지만, 많은 패키지가 JavaScript로 작성되어 있습니다. 선언 파일은 TypeScript에게 "이 JavaScript 코드는 이런 타입을 가지고 있다"고 알려주는 역할을 합니다.

선언 파일이란

.d.ts 확장자를 가진 파일입니다. 타입 정보만 담고 있으며, 런타임에 실행되는 코드는 없습니다. TypeScript 컴파일러가 타입 검사를 할 때만 사용됩니다.

패키지/
├── index.js    ← 실행되는 코드
└── index.d.ts  ← 타입 정보만 담긴 선언 파일

선언 파일 작성

// math.d.ts
export declare function add(a: number, b: number): number;
export declare function subtract(a: number, b: number): number;
export declare const PI: number;

export declare interface Point {
  x: number;
  y: number;
}

declare 키워드는 "이 값은 이미 JavaScript 어딘가에 존재한다"는 의미입니다. 선언만 하고 구현은 포함하지 않습니다.

전역 선언

라이브러리가 전역 변수를 추가할 때 선언합니다.

// global.d.ts
declare const __DEV__: boolean;
declare const __VERSION__: string;

declare function analytics(event: string, data?: Record<string, unknown>): void;

이렇게 선언하면 import 없이도 어디서든 해당 변수와 함수를 타입 안전하게 사용할 수 있습니다.

DefinitelyTyped와 @types

많은 JavaScript 라이브러리의 선언 파일이 DefinitelyTyped 저장소에 모여 있습니다. @types/ 접두사로 설치합니다.

npm install --save-dev @types/node
npm install --save-dev @types/react
npm install --save-dev @types/lodash

TypeScript는 node_modules/@types/ 아래 파일들을 자동으로 참조합니다.

DefinitelyTyped: 수천 개의 JavaScript 라이브러리에 대한 TypeScript 선언 파일을 모아둔 커뮤니티 저장소. @types/ 패키지는 여기서 관리됩니다.

직접 선언해야 하는 경우

@types/에 없는 패키지라면 직접 최소 선언을 작성합니다.

// src/@types/some-lib.d.ts
declare module "some-lib" {
  export function doSomething(config: { timeout: number }): Promise<void>;
  export const VERSION: string;
}

모든 API를 정밀하게 선언하기 어렵다면 일단 느슨하게 선언하고 점진적으로 개선합니다.

// 우선 any로 처리
declare module "some-lib" {
  const lib: any;
  export default lib;
}

자동 생성

TypeScript로 작성한 라이브러리를 배포할 때, tsconfig.json에서 declaration: true를 설정하면 컴파일 시 선언 파일이 자동으로 생성됩니다.

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./types",
    "outDir": "./dist"
  }
}

dist/
├── index.js       ← 컴파일된 JavaScript
└── types/
    └── index.d.ts ← 자동 생성된 선언 파일

package.json에서 타입 경로 지정

라이브러리를 배포할 때 types 필드로 선언 파일 위치를 알려줍니다.

{
  "name": "my-lib",
  "main": "./dist/index.js",
  "types": "./dist/types/index.d.ts"
}

TypeScript는 이 경로를 보고 타입 정보를 가져옵니다.

선언 파일 우선순위

TypeScript가 타입을 찾는 순서입니다.

1. 패키지 자체에 포함된 .d.ts
2. package.json의 "types" 필드
3. node_modules/@types/패키지명/
4. tsconfig.json의 typeRoots / types 설정

선언 파일은 JavaScript 생태계와 TypeScript 타입 시스템을 연결하는 다리입니다. 직접 작성할 일이 많지는 않지만, 구조를 이해하면 @types/ 패키지가 없는 라이브러리를 만났을 때 빠르게 대응할 수 있습니다.