JavaScript 프로젝트에 TypeScript 점진적으로 도입하기

배경

회사 메인 프로젝트는 2년 전부터 순수 JavaScript로 작성되어 왔다. 런타임 에러가 잦았고, 리팩토링 시 타입 추론이 불가능해 생산성이 떨어졌다. TypeScript 도입을 제안했지만 전체 코드베이스를 한 번에 전환하는 것은 현실적이지 않았다.

접근 방법

1. tsconfig.json 기본 설정

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "outDir": "./dist",
    "target": "ES2015",
    "module": "commonjs",
    "strict": false
  },
  "include": ["src/**/*"]
}

allowJs를 true로 설정해 기존 JS 파일과 새로운 TS 파일이 공존할 수 있게 했다. strict 모드는 초기엔 비활성화했다.

2. 신규 모듈부터 TS로 작성

새로 작성하는 코드는 무조건 .ts 확장자로 시작했다. 유틸 함수나 독립적인 모듈부터 적용했다.

// utils/validation.ts
export function isValidEmail(email: string): boolean {
  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return regex.test(email);
}

export function parseUserId(id: string | number): number {
  return typeof id === 'string' ? parseInt(id, 10) : id;
}

3. 주요 모델부터 인터페이스 정의

// types/user.ts
export interface User {
  id: number;
  email: string;
  name: string;
  createdAt: Date;
}

export interface ApiResponse<T> {
  success: boolean;
  data: T;
  error?: string;
}

기존 JavaScript 파일에서도 JSDoc으로 타입을 참조할 수 있게 했다.

4. 중요 파일 순차 전환

에러가 자주 발생하던 API 통신 레이어부터 .js를 .ts로 전환했다. 한 파일씩 작업하며 타입 에러를 해결했다.

결과

3개월간 진행하며 전체 코드의 약 40%를 TypeScript로 전환했다. 런타임 에러는 체감상 30% 정도 줄었고, IDE의 자동완성 덕분에 개발 속도가 빨라졌다. 팀원들도 점차 TypeScript의 이점을 인정하는 분위기다.

다음 분기에는 strict 모드를 켜고, 남은 핵심 모듈들을 전환할 계획이다.