JavaScript interop과 checkJs

기본 패턴

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "noEmit": true
  }
}

/** @param {number} a @param {number} b */
export function add(a, b) {
  return a + b;
}

설명

• 많은 팀이 순수 TypeScript 프로젝트로 시작하지 않습니다. 이미 JavaScript 코드가 큰 상태에서 점진적으로 타입 안정성을 높이는 경우가 훨씬 많습니다.
• allowJs는 JavaScript 파일을 프로젝트에 포함하게 하고, checkJs는 그 파일에도 타입 검사를 적용하게 합니다. 즉 "한 번에 전부 변환"이 아니라 "조금씩 검사 강도를 높이는" 전략이 가능해집니다.
• JSDoc은 JavaScript 파일 안에서 타입 힌트를 붙이는 방법입니다. 함수 인자, 반환값, 객체 구조를 어느 정도 설명할 수 있어서 마이그레이션 초기 단계에 특히 유용합니다.
• 이 접근의 핵심은 마이그레이션 비용을 분산시키는 데 있습니다. 새 파일은 .ts, 기존 코드는 .js + JSDoc로 유지하면서 점차 strict한 구역을 넓혀 갈 수 있습니다.
• TypeScript 도입은 문법 전환만이 아니라 팀의 안정성 전략입니다. 그래서 "지금 전체 변환이 가능한가"보다 "어떤 경계부터 타입 검사를 붙일 것인가"를 먼저 보는 편이 좋습니다.

빠른 정리

주의할 점