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 파일)만을 포함합니다.

타입스크립트 컴파일러는 명시적으로 import한 모듈의 선언을 해석할 때 설치된 @types 패키지를 사용할 수 있습니다. 전역 선언의 자동 포함은 별도 설정이며, TypeScript 6.0 이상에서는 types의 기본값이 []이므로 필요한 전역 패키지를 명시합니다.

사용 예시

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

lodash 라이브러리 설치

npm install lodash

lodash에 대한 타입 정의 설치

npm install --save-dev @types/lodash

--save-dev는 개발 의존성으로 기록합니다. 실제 설치 여부는 배포·설치 옵션에 달려 있습니다. 애플리케이션의 빌드용 타입은 개발 의존성으로 둘 수 있지만, 배포할 .d.ts가 다른 타입 패키지를 참조하면 소비자가 받도록 의존성 배치를 검토해야 합니다.

이제 타입스크립트 코드에서 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'); // string shorthand가 허용되므로 이 호출을 타입 오류 예시로 볼 수 없습니다.
// 타입 선언이 허용하는 shorthand까지 실제 속성 존재를 증명하는 것은 아닙니다.

`@types` 패키지의 장점

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

`@types` 패키지가 없을 때

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

직접 .d.ts 파일 작성: 해당 라이브러리의 외부 API를 파악하여 직접 앰비언트 모듈 선언(.d.ts 파일)을 작성합니다 (8장 3절 참조).

이 방법은 라이브러리의 규모가 작거나, 사용하려는 부분이 제한적일 때 유용합니다.

my-lib-declaration.d.ts

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

app.ts

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

any 타입으로 사용 (최후의 수단): 정의된 타입이 없어 타입 안정성을 포기하고 any 타입으로 라이브러리를 사용하는 방법입니다.

app.ts

import SomeUntypedLib from 'some-untyped-lib'; // 선언 누락을 허용하는 설정에서는 any이며, strict에서는 오류가 날 수 있음
const lib = new SomeUntypedLib();
lib.doSomethingElse(123); // 타입 검사 없이 허용

이 방법은 타입스크립트 사용의 이점을 상실하므로 가능한 한 피해야 합니다.

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

BUNDLED · @TYPES · LOCAL DECLARATION

라이브러리 타입 소스 선택

패키지 자체 선언을 먼저 확인하고, 없을 때 호환되는 @types와 좁은 local declaration을 순서대로 선택하며 runtime shape를 함께 검증한다.

exports types 조건?
PACKAGE — types · typings · typesVersions
자체 declaration 사용
BUNDLED — obsolete @types 제거 확인
compatible package
@TYPES — 지원 API range 검증
좁은 declare module
LOCAL — 실제 export shape만 기술
consumer fixture
COMPILE — module mode에서 resolve
runtime version/shape
SMOKE — 타입과 구현 일치 확인

declaration은 구현을 만들지 않는다. 배포되는 .d.ts가 @types를 참조하면 dependency 배치도 소비자 관점에서 검토한다.

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

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

my-typescript-lib/package.json

{
  "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·exports의 타입 조건 등을 확인하고 중복 @types 설치를 피합니다.
자체 선언이 없음: 구현 버전과 호환되는 @types/<라이브러리명>을 확인합니다.
@types에도 없음: 직접 .d.ts 파일 작성 또는 any 사용.

`tsconfig.json`의 `types` 및 `typeRoots` 옵션

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

typeRoots: 자동 전역 포함에 사용할 타입 패키지 루트를 지정한 목록으로 제한합니다. 기본 루트에 단순히 더하는 옵션이 아니므로, 아래 예제는 기본 @types 경로도 명시합니다. 커스텀 루트에는 패키지별 선언 디렉토리를 둡니다.
```
"compilerOptions": {
  "typeRoots": ["./node_modules/@types", "./custom-types"] // custom-types 디렉토리도 검색
}
```
types: 컴파일러가 전역 타입 선언으로 포함할 @types 패키지 목록을 지정합니다. TypeScript 6.0 이상에서 이 옵션의 기본값은 []입니다. 이전 버전은 보이는 타입 패키지를 기본적으로 포함했지만, 명시한 types 목록은 전역에 포함할 패키지를 제한합니다.
```
"compilerOptions": {
  "types": ["node", "jest"] // 오직 @types/node와 @types/jest만 포함하고 싶을 때
}
```
버전별 기본값과 명시적 import에 미치는 영향은 공식 types 문서를 함께 확인합니다. 이는 자동 전역 타입의 충돌을 줄이는 설정입니다. JavaScript 번들 크기를 직접 줄이지 않으며 명시적으로 import한 모듈의 타입 해석도 막지 않습니다.

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

명시적 import의 모듈 해석과 전역 타입 포함은 별도 경로다. types 목록은 import한 모듈의 타입 해석을 차단하지 않는다.

모듈 경로
import한 패키지나 로컬 파일의 선언을 설정에 따라 해석한다.
전역 경로
typeRoots로 루트를, types로 전역에 포함할 타입 패키지를 선택한다.
합류와 진단
두 경로가 타입 환경을 구성한다. 모듈 해석 실패, 전역 이름 누락, 중복 선언, 런타임 경로 불일치를 구분한다.

TypeScript 6.0 이상은 types의 기본값이 []이다. 이전 버전의 기본 자동 포함과 구분하고 필요한 node·jest 등을 명시한다.

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

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

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

새 라이브러리는 자체 선언과 export 형식을 먼저 확인하고, 없을 때 호환되는 @types를 찾습니다.

DefinitelyTyped 프로젝트란?

@types 스코프 패키지

@types 패키지의 장점

@types 패키지가 없을 때