기존 자바스크립트 프로젝트를 타입스크립트로 전환하는 길

자바스크립트로 구축한 프로젝트가 충분히 성장했다면, 더 안전하고 유지보수가 쉬운 코드로 거듭나기 위해 타입스크립트 도입을 고민하게 된다. 이 장에서는 기존 자바스크립트 코드를 타입스크립트로 바꾸는 실제적인 흐름과 그 과정에서 마주칠 수 있는 문제, 그리고 효과적인 정착 방식에 대해 살펴본다.

변경의 출발점: 점진적인 도입

타입스크립트는 자바스크립트의 상위 집합이므로, 기존 코드를 한 번에 모두 바꿀 필요 없다. 프로젝트의 폴더 구조와 빌드 도구를 점검한 뒤, 타입스크립트 설정 파일(tsconfig.json)을 추가하는 것부터 시작하면 된다. 점차적으로 관련 파일들을 .js에서 .ts 또는 .tsx로 확장자를 바꿔가며, 타입 체크를 강화할 수 있다.

tsconfig.json 파일로 프로젝트를 컨트롤하다

타입스크립트의 시작은 tsconfig.json 생성에서 출발한다. 이 설정 파일을 통해 어떤 파일을 컴파일할지, 어떤 수준까지 엄격하게 검사할지 조정할 수 있다. "strict" 옵션을 켜면 타입 안정성이 크게 높아진다. allowJs 옵션은 기존 .js 파일을 타입스크립트 프로젝트에 포함시켜 점진적 전환을 자연스럽게 돕는다.

파일 확장자 변경과 오류 파악

변환 과정은 파일의 확장자를 하나씩 .ts로 바꾸는 것에서 비롯된다. 단, jsx 구문을 포함한 리액트 파일은 .tsx를 사용해야 한다. 파일 확장자만 바꿔도 에디터와 컴파일러는 코드 내 타입 관련 실수와 애매한 부분을 즉시 경고해준다. 여기서부터 타입 선언을 추가하거나, any를 임시로 사용하며 차근차근 타입을 명확하게 표현해 나가면 된다.

타입 선언과 점진적 개선

초기에는 any, unknown 같은 느슨한 타입을 임시로 활용할 수 있지만, 점차 interface, type alias, 제네릭 등 TS 고유 도구를 적극적으로 써서 각 객체와 함수의 구조를 명확히 해야 한다. 외부 라이브러리를 사용한다면 DefinitelyTyped에서 제공하는 타입 선언(@types/...)도 함께 설치해준다.

테스트와 디버깅의 중요성

함께 테스트 코드를 보완하고, 런타임과 타입 검사 과정에서 발생하는 오류를 꼼꼼히 수정하는 것이 성공적 전환의 핵심이다. ESLint 및 타입스크립트 전용 플러그인을 활용하면 코드 품질을 자동으로 유지할 수 있다.

전환의 과정을 통해 얻는 것

타입스크립트로의 마이그레이션을 거치면, 팀원 간 소통의 정확성이 높아지고, 잘못된 데이터 처리나 함수 사용 실수가 눈에 띄게 줄어든다. 변화의 첫발은 두렵지만, 소규모 모듈부터 차분히 바꿔간다면 오래된 프로젝트도 현대적이고 튼튼하게 되살릴 수 있다. 한 번 시작하면, 더는 자바스크립트만으로 돌아가기 어렵다는 개발자들의 후기가 괜히 나온 것이 아니다.