JS 파일로 .d.ts 만들기

JS 파일로 .d.ts 만들기 (Creating .d.ts Files from .js files)

도입

JavaScript 프로젝트를 그대로 두면서도 TypeScript 편집기의 도움을 받고 싶을 때가 있어요. 처음부터 TypeScript로 이전(porting)하거나 코드베이스에 .d.ts 파일을 쭉 관리하는 건 부담스럽죠. 이 문서에서 다루는 방법을 쓰면, 그런 부담 없이 JSDoc 주석만으로 선언 파일을 만들어낼 수 있어요.

출처: TypeScript 공식문서

본문

TypeScript 3.7(정확히는 --declaration과 --allowJs를 함께 쓴 경우)부터, TypeScript가 JSDoc 문법을 이용해 JavaScript에서 .d.ts 파일을 생성하는 기능을 지원했어요. 이렇게 하면 프로젝트를 TypeScript로 옮기지 않고도, 유지보수할 .d.ts 파일을 따로 들고 다니지 않아도 TypeScript 기반 편집기의 경험을 그대로 누릴 수 있어요.

TypeScript는 대부분의 JSDoc 태그를 지원해요. 지원되는 태그 목록은 여기 있는 reference에서 확인할 수 있어요.

프로젝트에서 `.d.ts` 파일을 내보내도록 설정하기

프로젝트에 .d.ts 파일 생성 기능을 추가하려면, 크게 네 단계를 거쳐요.

devDependencies에 TypeScript를 추가하고
TypeScript를 설정하는 tsconfig.json을 만들고
타입스크립트 컴파일러를 실행해서 JS 파일에 대응하는 .d.ts 파일을 만들고
(선택) package.json을 수정해서 타입을 연결해 줘요

TypeScript 추가하기

타입스크립트 설치는 installation page에서 자세히 볼 수 있어요.

TSConfig

TSConfig는 컴파일러 플래그를 설정하고, 어떤 파일을 찾을지 선언하는 jsonc 파일이에요. 이번 경우에는 대략 이런 파일을 쓰면 돼요.

{
  // Change this to match your project
  "include": ["src/**/*"],
  "compilerOptions": {
    // Tells TypeScript to read JS files, as
    // normally they are ignored as source files
    "allowJs": true,

    // Generate d.ts files
    "declaration": true,

    // This compiler run should
    // only output d.ts files
    "emitDeclarationOnly": true,

    // Types should go into this directory.
    // Removing this would place the .d.ts files
    // next to the .js files
    "outDir": "dist",

    // go to js file when using IDE functions like
    // "Go to Definition" in VSCode
    "declarationMap": true
  }
}

여기서 allowJs는 평소에 소스 파일로 무시되는 JS 파일을 TypeScript가 읽게 해 주는 옵션이고, declaration: true로 선언 파일을 만들며, emitDeclarationOnly: true로 이번 컴파일은 .d.ts 파일만 내보내도록 해요. 타입은 outDir에 지정한 디렉터리로 들어가요(이걸 빼면 .d.ts 파일이 .js 파일 옆에 놓여요). 그리고 declarationMap: true는 VSCode 같은 IDE에서 "Go to Definition" 같은 기능을 쓸 때 JS 파일로 이동하게 해 줘요.

각 옵션에 대해 더 알고 싶다면 tsconfig reference를 보면 돼요.

TSConfig 파일 대신 CLI를 쓸 수도 있어요. 아래 명령은 위 설정과 같은 동작을 해요.

npx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types

컴파일러 실행하기

컴파일러 실행 방법도 installation page에서 확인할 수 있어요. 만약 프로젝트의 .gitignore에 해당 파일들이 들어 있다면, 패키지에 이 파일들이 포함되도록 꼭 챙겨야 해요.

`package.json` 수정하기

TypeScript는 package.json에서 모듈을 찾는 node resolution을 그대로 따르되, .d.ts 파일을 찾는 단계를 하나 더 추가해요. 대략적인 우선순위는 이래요. 먼저 선택 옵션인 types 필드를 확인하고, 그다음 "main" 필드를 확인하며, 마지막으로 루트의 index.d.ts를 시도해요. types 필드가 없으면 "main"이 쓰여요.

팁

.d.ts 파일을 위한 테스트를 쓰고 싶다면 tsd나 TSTyche를 시도해 보세요.

JS 파일로 .d.ts 만들기