핵심 정리

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

/** @param {string} name */
export function greet(name) {
  return `Hello, ${name}`;
}

JS 연동

점진 도입에서 먼저 보는 기본형은 아래입니다.

• .js를 프로젝트에 포함: allowJs
• .js 타입 검사 활성화: checkJs
• JSDoc으로 함수 계약 추가
• 출력은 막고 검사만 수행: noEmit

1) JS 파일을 유지하면서 읽으려면 allowJs

기존 JavaScript 파일을 TypeScript 프로젝트 안에 함께 두려면 보통 allowJs를 봅니다. 이 설정만으로도 .js 파일을 함께 다룰 수 있습니다.

2) 실제 타입 검사까지 하려면 checkJs

allowJs만으로는 읽기만 할 뿐, 타입 검사 이점은 제한적입니다. JSDoc과 함께 .js 파일에도 오류 검사를 걸고 싶다면 checkJs가 핵심입니다.

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

현재 TypeScript 문서 기준으로 checkJs는 allowJs와 함께 동작하는 옵션입니다. 그래서 검사 중심 프로젝트를 설명할 때는 "JavaScript 파일을 포함하려면 allowJs, 그 파일까지 검사하려면 checkJs"라는 순서로 읽는 편이 가장 안전합니다.

3) 경계부터 JSDoc 계약을 붙인다

모든 내부 구현보다 먼저 export 함수, 주요 데이터 shape, 외부 입력 경계부터 JSDoc 타입을 붙이는 편이 효과가 빠릅니다.

/** @returns {{ id: string, name: string }} */
function getUser() {
  return { id: "u1", name: "Mina" };
}

즉 마이그레이션은 파일 수보다 계약 경계를 먼저 잡는 전략이 낫습니다.

4) noEmit으로 검사 전용 모드로 둘 수도 있다

실제 JS 출력은 번들러에게 맡기고 TypeScript는 검사만 하게 두는 경우 noEmit: true가 자연스럽습니다. 점진 도입 단계에서 특히 많이 씁니다.

5) 완전 변환 전에도 체감 이득을 먼저 얻을 수 있다

checkJs와 JSDoc만으로도 IDE 도움과 기본 오류 검사가 들어오므로, .ts 전환 전에 품질 기준선을 어느 정도 올릴 수 있습니다.

• 전체 변환이 멀다: allowJs + checkJs
• 공개 API부터 계약을 붙인다: JSDoc 우선
• 배포 출력은 이미 다른 도구가 맡는다: noEmit

언제 checkJs를 쓸까

• 기존 JS를 함께 둔다: allowJs 또는 checkJs
• JS에도 타입 검사를 건다: checkJs
• 실행 출력은 번들러가 맡는다: noEmit: true
• 마이그레이션 우선순위다: 공개 경계/핵심 모듈부터
• JSDoc만으로도 먼저 계약을 붙일 수 있다

주의할 점

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