Definitely Typed: TypeScript의 타입 정의 저장소

타입스크립트 프로젝트에서 @types/로 시작하는 수 많은 패키지가 개발 의존성으로 설치되어 있는 것을 보신 적이 있으신가요? 이번 포스팅에서는 이러한 패키지들이 도대체 왜 필요하며 어디서 오는 것인지에 대해서 간단히 알아보려고 합니다.

Definitely Typed란?

자바스크립트는 생겨난지 30년이 다 되가는 프로그래밍 언어이지만 타입스크립트는 이제 겨우 탄생한지 10년이 조금 넘었습니다. 최근에 만들어진 자바스크립트 패키지는 대부분은 타입 선언(type definitions)이 내장되어 있지만, 타입스크립트가 등장하기 이전에 만들어진 많은 패키지들이 타입을 제공하지 않습니다. 대표적인 예로 백엔드 개발에서 많이 사용되는 익스프레스(Express)와 프론트엔드 개발에 많이 사용되는 리액트(React)를 들 수 있죠.

Definitely Typed는 이렇게 타입 선언이 누락된 자바스크립트 패키지들를 위한 타입 저장소입니다. 이 곳에는 익스프레스나 리액트 뿐만 아니라, 우리가 사용하는 대부분의 역사가 오래된 자바스크립트 라이브러리와 프레임워크에 대한 타입이 선언되어 있습니다. 각 패키지에 대한 타입은 .d.ts 확장자를 가진 타입 선언 파일로 제공되면 @types 범위(scope)로 npm 저장소에 발행(publish)하도록 약속되어 있습니다. 예를 들어, 익스프레스의 패키지 명은 express이기 때문에, 타입 선언을 담고있는 패키지의 이름은 @types/express입니다. 마찬가지로, react 패키지에 대한 타입 선언은 @types/react에 담겨 있습니다.

타입스크립트 프로젝트에서 이렇게 타입 선언이 누락된 자바스크립트를 사용할 때는 그에 상응하는 @types로 시작하는 타입 패키지도 설치해주는 것이 좋은데요. 타입스크립트 컴파일러가 해당 프로젝트를 컴파일할 때 타입 오류를 잡아낼 수 있기 때문입니다. 뿐만 아니라, 코드 편집기에서도 자동 완성과 같은 부가적인 기능이 제공되므로 개발자 실수를 줄임과 동시에 개발자 경험도 향상됩니다. 굳이 API 문서를 보지 않더라도 코드 편집기 내에서 해당 패키지의 API를 빠르게 파악할 수 있기 때문에 개발 생산성 측면에서도 이점이 있습니다.

자바스크립트 런타임의 경우 약간 다른 이유로 타입 선언을 별도의 패키지로 발행하는데요. 바로 런타임 자체가 자바스크립트로 쓰여있지 않기 때문에 자바스크립트 패키지 저장소인 npm에 발행할 이유가 없기 때문입니다.

패키지 설치

타입 선언이 누락된 패키지를 설치할 때는 해당 패키지 자체와 타입 선언을 담고 있는 패키지, 이렇게 총 2개의 패키지를 설치해줘야 합니다.

여기서 주의할 점은 패키지 자체는 일반 의존성으로 설치하지만, 타입 선언을 담고 있는 패키지는 일반적으로 개발 의존성(dev dependency)로 설치한다는 점인데요. 왜냐하면 애플리케이션이 실행할 때는 굳이 타입 선언 정보가 필요없기 때문입니다. 타입 선언 정보는 코드 편집기와 같은 개발 도구와 타입스크립트 컴파일러가 타입스크립트 코드를 자바스크립트도 변환할 때만 필요합니다.

그럼 프로젝트에 익스프레스에 리액트를 설치해볼까요?

Node.js 프로젝트에서는 터미널에서 npm add 명령어로 패키지를 설치합니다.

$ npm add express react
$ npm add -D @types/express @types/react

Bun을 사용하는 프로젝트에서는 bun add 명령어로 패키지를 설치합니다.

$ bun add express react
$ bun add -D @types/express @types/react

package.json 파일을 열어보면 다음과 같이 설치 패키지가 명시되어 있는 것을 보실 수 있으실 것입니다.

  "dependencies": {
    "express": "^4.17.21",
    "react": "^18.3.3"
  },
  "devDependencies": {
    "@types/express": "^4.17.21",
    "@types/react": "^18.3.3",
  },

타입스크립트 설정

타입스크립트는 아무 설정을 해주지 않아도 컴파일할 때 기본적으로 프로젝트에 설치된 @types/로 시작하는 모든 패키지가 담고 있는 타입 선언을 참조하도록 되어 있습니다. 하지만 특정 패키지의 타입 선언만 참조하게 하고 싶다면 다음과 같이 컴파일러 옵션의 types 항목에 해당 패키지를 나열해주면 됩니다.

예를 들어, 익스프레스와 리액트의 타입 선언 패키지, 즉 @types/express와 @types/react만 타입스크립트 컴파일러가 참조하게 설정하고 싶다면 다음과 같이 tsconfig.json 파일에 명시해주면 됩니다.

{
  "compilerOptions": {
    "types": ["express", "react"]
  }
}

이렇게 설정해줄 경우, @types/axios와 같은 다른 타입 선언 패키지가 프로젝트에 설치되어 있더라도 무시가 되므로 주의가 필요합니다.

자, 여기까지만 진행해주시면 코드 편집기에서 express나 react를 불러와서 사용할 때, 빨간 줄이 그어지지 않고 자동 완성도 잘 될 것입니다. 물론 타입스크립트 컴파일러도 아무 문제없이 자바스크립트 코드로 컴파일을 해줄 것입니다.

마치면서

지금까지 Definitely Typed 활용하여 타입스크립트 프로젝트에서 어떻게 타입 선언이 누락되어 있는 자바스크립트 패키지를 타입 오류없이 사용할 수 있는지 살펴보았습니다.

참고로 Definitely Typed는 오픈소스 프로젝트이기 때문에 누구나 기여할 수 있습니다. 새로운 타입 정의를 추가하거나 기존 타입 정의를 개선하는 것에 참여할 수 있죠. 또한, Definitely Typed 커뮤니티는 GitHub를 통해 활발하게 소통하고 있으며, 문제를 보고하거나 질문을 할 수 있는 공간을 제공하고 있습니다. 오픈소스 기여에 관심이 있으시다면 Definitely Typed 프로젝트에서 시작하시는 것도 좋은 방법일 것입니다.