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

배경

팀 내에서 TypeScript 도입 논의가 있었다. 하지만 2년간 운영한 프로젝트를 한 번에 전환하기엔 리스크가 컸다. 점진적 마이그레이션 전략을 세워 진행했다.

초기 설정

tsconfig.json을 프로젝트 루트에 추가하고 allowJs 옵션을 활성화했다.

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

allowJs를 true로 설정하면 .js와 .ts 파일이 공존할 수 있다. checkJs는 false로 두어 기존 JavaScript 파일에서 타입 에러가 발생하지 않도록 했다.

마이그레이션 순서

1. 유틸 함수부터 시작: 의존성이 적은 utils, helpers 폴더의 파일을 .ts로 변경
2. 타입 정의 추가: 자주 사용하는 데이터 구조를 interface로 정의
3. 새 기능은 TypeScript로: 신규 컴포넌트, 모듈은 무조건 .tsx/.ts로 작성

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

// utils/userHelper.ts
import { User } from '../types/user';

export function getFullName(user: User): string {
  return user.name || user.email;
}

주의사항

• strict 모드는 나중에 활성화: 초기엔 false로 두고 점차 엄격하게
• any 타입 허용: 완벽한 타입보다는 일단 동작하는 코드 우선
• 빌드 도구 설정: webpack의 ts-loader나 awesome-typescript-loader 추가 필요

// webpack.config.js
module.exports = {
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx']
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/
      }
    ]
  }
};

결과

3개월간 진행하여 전체 코드의 약 40%를 TypeScript로 전환했다. 런타임 에러가 눈에 띄게 줄었고, IDE 자동완성이 개선되어 개발 속도도 향상되었다. 급하게 전환하지 않은 것이 좋은 선택이었다.