프로젝트에 TypeScript 도입하기 - 점진적 마이그레이션 전략

배경

팀 내에서 TypeScript 도입 논의가 있었다. 3만 줄 규모의 React 프로젝트를 한 번에 마이그레이션하는 것은 현실적으로 어려웠고, 점진적 전환 방식을 선택했다.

설정

tsconfig.json에서 핵심은 allowJs와 checkJs 옵션이었다.

{
  "compilerOptions": {
    "target": "es5",
    "module": "esnext",
    "lib": ["dom", "es2017"],
    "jsx": "react",
    "allowJs": true,
    "checkJs": false,
    "strict": false,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

allowJs를 켜면 .js와 .ts 파일이 공존할 수 있다. strict는 초반엔 꺼두고, 팀원들이 적응한 후 단계적으로 활성화할 계획이다.

마이그레이션 순서

1. 유틸 함수부터 시작 - 의존성이 적고 테스트 커버리지가 높음
2. 타입 정의 파일 작성 - 기존 모듈에 대한 d.ts 파일
3. 새 기능은 무조건 TS로 작성
4. 리팩토링 시점에 기존 파일 전환

초기 어려움

라이브러리 타입 정의가 없는 경우가 많았다. @types 패키지를 찾거나, 직접 .d.ts를 작성해야 했다.

// src/types/custom.d.ts
declare module 'legacy-library' {
  export function doSomething(param: string): void;
}

효과

2주간 약 30개 파일을 전환했다. IDE의 자동완성이 정확해지고, 리팩토링 시 confidence가 높아졌다. 특히 props 타입 체크로 컴포넌트 사용 오류를 사전에 잡을 수 있었다.

당분간은 .js와 .ts가 혼재된 상태로 운영하되, 6개월 내 80% 이상 전환을 목표로 하고 있다.