DefinitelyTyped와 @types

타입스크립트로 자바스크립트 라이브러리를 개발하거나, 기존 라이브러리를 타입스크립트 프로젝트에서 사용할 때 핵심은 타입 정의 파일(.d.ts)입니다.

문제는 라이브러리 수가 너무 많아 모든 .d.ts를 개발자가 직접 작성하는 것이 비효율적이고 사실상 불가능에 가깝다는 점입니다.

이러한 문제를 해결하기 위해 등장한 것이 바로 DefinitelyTyped 프로젝트와 npm의 @types 스코프 패키지입니다.

DefinitelyTyped 프로젝트란?

DefinitelyTyped는 수많은 자바스크립트 라이브러리에 대한 고품질의 타입 정의 파일을 제공하는 오픈 소스 프로젝트입니다.

전 세계의 개발자들이 자발적으로 참여하여 각 라이브러리의 .d.ts 파일을 작성하고 유지보수하며, 이를 통해 타입스크립트 사용자들이 자바스크립트 생태계를 타입 안전하게 활용할 수 있도록 돕습니다.

DefinitelyTyped는 GitHub 저장소(https://github.com/DefinitelyTyped/DefinitelyTyped)에서 관리되며, 각 라이브러리별 타입 정의 파일이 별도 디렉토리에 존재합니다.

예를 들어 Lodash 라이브러리 타입 정의는 DefinitelyTyped/types/lodash 경로에 있습니다.

@types 스코프 패키지

DefinitelyTyped에 기여된 모든 타입 정의 파일은 자동으로 npm의 @types 스코프로 패키징되어 배포됩니다.

즉, lodash 라이브러리에 대한 타입 정의는 npm install @types/lodash 명령어로 설치할 수 있게 됩니다.

이 @types 패키지들은 실제 자바스크립트 코드를 포함하지 않고, 오직 해당 라이브러리의 타입 정의(.d.ts 파일)만을 포함합니다.

타입스크립트 컴파일러는 기본적으로 node_modules/@types 디렉토리를 자동으로 검색하여 필요한 타입 정의 파일을 찾습니다.

lodash 라이브러리를 타입스크립트 프로젝트에서 사용하려고 할 때:

npm install lodash

npm install --save-dev @types/lodash

이제 타입스크립트 코드에서 lodash를 가져와 사용하면, 타입스크립트 컴파일러는 node_modules/@types/lodash 경로의 .d.ts 파일을 참조하여 _ 객체의 모든 메서드와 속성에 대한 정확한 타입 정보를 제공합니다.

import _ from 'lodash'; // 'lodash' 모듈을 가져옴 (CommonJS 모듈이므로 esModuleInterop: true 권장)

const numbers = [1, 2, 3, 4, 5];
const sum = _.sum(numbers); // sum은 number 타입으로 추론됩니다. (정확한 매개변수 힌트 제공)
console.log(sum); // 15

const shuffled = _.shuffle(numbers); // shuffled는 number[] 타입으로 추론됩니다.
console.log(shuffled);

// _.sortBy(numbers, 'invalidKey'); // Error: 'string' 형식은 'lodash.ValueIteratee<number>' 형식에 할당될 수 없습니다.
                                  // 타입 정의 덕분에 잘못된 인자 사용 시 오류를 즉시 감지합니다.

@types 패키지의 장점

• 자동 완성 및 타입 검사: IDE에서 라이브러리 사용 시 정확한 자동 완성(_.)과 함수 시그니처 힌트를 제공하여 개발 생산성을 크게 높입니다. 잘못된 인자 전달이나 존재하지 않는 메서드 호출 등의 오류를 컴파일 시점에 즉시 잡아줍니다.
• 쉬운 통합: npm install 한 줄로 수많은 자바스크립트 라이브러리를 타입스크립트 프로젝트에 타입 안전하게 통합할 수 있습니다.
• 커뮤니티 주도: 전 세계 개발자들의 기여로 최신 라이브러리 버전에도 빠르게 대응하고, 버그 수정 및 개선이 활발하게 이루어집니다.
• 명확한 버전 관리: @types 패키지는 해당 라이브러리의 특정 버전(또는 범위)에 맞는 타입 정의를 제공하므로, 라이브러리 버전과 타입 정의 버전 간의 호환성을 관리하기 용이합니다.

@types 패키지가 없을 때

만약 특정 자바스크립트 라이브러리에 대한 @types 패키지가 존재하지 않는다면, 다음 두 가지 방법 중 하나를 선택할 수 있습니다.

declare module 'my-custom-js-lib' {
  export function doSomething(param: string): number;
}

import { doSomething } from 'my-custom-js-lib';
doSomething('hello');

import SomeUntypedLib from 'some-untyped-lib'; // 타입 정보가 없으므로 SomeUntypedLib는 any 타입
const lib = new SomeUntypedLib();
lib.doSomethingElse(123); // 타입 검사 없이 허용

아래 다이어그램은 새 라이브러리를 도입할 때 타입 정의를 찾는 우선순위와, 없을 때 선택지를 비교합니다.

라이브러리가 자체적으로 타입 정의를 제공하는 경우

"types": "dist/index.d.ts"

일부 최신 자바스크립트 라이브러리(특히 타입스크립트로 작성된 라이브러리)는 package.json 파일의 types (또는 typings) 필드를 통해 자체적으로 타입 정의 파일을 포함하여 배포합니다.

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

기존 package.json에 적용할 때는 main과 types 키를 병합하고 다른 스크립트와 메타데이터는 유지합니다.

이러한 라이브러리들은 @types 패키지를 별도로 설치할 필요가 없습니다.

npm으로 라이브러리를 설치하면 타입스크립트 컴파일러가 package.json의 types 필드를 참조하여 자동으로 타입 정의를 찾습니다.

• 라이브러리가 자체 types 필드를 가짐: @types 설치 필요 없음.
• 라이브러리가 자체 types 필드를 가지지 않음: @types/<라이브러리명> 설치 시도.
• @types에도 없음: 직접 .d.ts 파일 작성 또는 any 사용.

tsconfig.json의 types 및 typeRoots 옵션

tsconfig.json 파일의 compilerOptions에서 types와 typeRoots 옵션을 사용하여 타입 정의 파일의 검색 방식을 더 세밀하게 제어할 수 있습니다.

• typeRoots: node_modules/@types와 같이 타입 정의 파일을 검색할 루트 디렉토리 목록을 지정합니다. 기본적으로 node_modules/@types가 포함되어 있으므로, 대부분의 경우 명시할 필요는 없습니다. 하지만 @types가 아닌 특정 커스텀 타입 정의 경로를 추가하고 싶을 때 사용합니다.

  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./custom-types"] // custom-types 디렉토리도 검색
  }

• types: 컴파일러가 전역 타입 선언으로 포함할 @types 패키지 목록을 지정합니다. 이 옵션이 없으면 typeRoots에 있는 모든 @types 패키지가 자동으로 포함되지만, types를 명시하면 여기에 나열된 패키지만 포함됩니다.

  "compilerOptions": {
    "types": ["node", "jest"] // 오직 @types/node와 @types/jest만 포함하고 싶을 때
  }

  이는 번들링 크기를 줄이거나, 불필요한 전역 타입 충돌을 피하고 싶을 때 유용합니다.

아래 다이어그램은 types와 typeRoots가 전역 타입 선언의 포함 범위를 어떻게 좁히는지 정리합니다.

@types를 설치할지, 자체 타입을 믿을지, 직접 선언을 둘지 결정할 때는 패키지의 현재 배포 형태와 프로젝트의 전역 타입 범위를 같이 확인해야 합니다.

DefinitelyTyped와 @types는 타입스크립트 생태계의 핵심이며, 자바스크립트와 타입스크립트 간 호환성을 보장하는 중요한 메커니즘입니다.

이를 통해 수많은 기존 자바스크립트 라이브러리를 타입 안전하게 활용할 수 있어, 타입스크립트 도입 장벽을 낮추고 개발 생산성을 높일 수 있습니다.

새 라이브러리를 사용할 때는 @types 패키지 존재 여부를 먼저 확인하는 습관을 들이는 것이 좋습니다.

다음 다이어그램은 DefinitelyTyped와 @types 패키지를 타입 제공 방식 기준으로 정리한 표입니다.

아래 다이어그램은 DefinitelyTyped 프로젝트와 @types 스코프 패키지가 타입 해석과 빌드 결과에 주는 영향을 정리합니다.