JS 프로젝트에 TypeScript 얹어봤더니 이랬다

어쩌다 TypeScript 마이그레이션을 시작했냐면

솔직히 말하면 처음엔 별로 하고 싶지 않았다. 돌아가고 있는 코드에 손대는 건 항상 리스크니까. 근데 프로젝트 규모가 커지면서 진짜로 버티기 힘들어졌다. 어떤 함수가 뭘 반환하는지, 파라미터에 뭘 넣어야 하는지 코드 열 줄 읽어야 알 수 있는 상태가 됐고, 그때부터 마이그레이션을 시작했다.

결론부터 말하면 — 후회 없다. 다만 방법을 모르고 시작했다면 중간에 포기했을 것 같다.

점진적 마이그레이션이 핵심이다

가장 큰 실수는 "한 번에 다 바꾸겠다"는 생각이다. TypeScript로 프로젝트를 통째로 전환하려다 중간에 빌드가 터지면 손도 못 쓴다. 실제로 쓸 만한 접근은 점진적 마이그레이션이다.

1단계: tsconfig.json을 느슨하게 시작해라

처음부터 strict 모드로 시작하면 오류가 수백 개 터진다. 이렇게 시작해볼 것:

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "strict": false,
    "noImplicitAny": false
  }
}

allowJs: true로 설정하면 .js 파일과 .ts 파일을 같은 프로젝트에서 섞어 쓸 수 있다. 파일 하나씩 바꿔가는 게 가능해진다.

2단계: 핵심 타입 파일부터 먼저 바꿔라

API 응답 타입, 공통 유틸 함수, 상태 타입 같은 것들이 제일 자주 쓰이는 파일이다. 이것들을 먼저 .ts로 전환하면 다른 파일들이 자동으로 타입 힌트를 받기 시작한다. 개인적으로 이 단계에서 "아, 이래서 쓰는 거구나" 싶었다.

3단계: any 타입은 TODO로 남겨둬라

빠르게 마이그레이션하다 보면 모르는 타입에 any를 박게 된다. 이걸 그냥 두면 나중에 찾기 힘드니까 // TODO: fix any 주석을 꼭 달아둘 것. 나중에 grep으로 한 번에 찾을 수 있다.

실제로 도움됐던 것들

타입 추론을 믿어라

처음엔 모든 변수에 타입을 명시했다. const name: string = 'hello' 이런 식으로. 근데 TypeScript가 알아서 추론하는 경우가 훨씬 많다. 오히려 명시하면 코드가 지저분해진다. 타입을 직접 써야 하는 경우는 함수의 파라미터와 반환값 정도면 충분하다.

타입 가드 패턴

API 응답 같은 외부 데이터는 타입이 보장이 안 된다. 이때 타입 가드가 유용하다:

function isUser(data: unknown): data is User {
  return typeof data === 'object' 
    && data !== null 
    && 'id' in data 
    && 'name' in data;
}

이 패턴 하나 알면 서버 응답 처리할 때 훨씬 안전해진다.

@types 패키지 확인

라이브러리 대부분은 @types/라이브러리명 패키지가 있다. 없다면 declare module '라이브러리명'으로 최소한의 타입 선언이라도 만들어야 한다. 그냥 any로 막아놓으면 나중에 더 힘들어진다.

예상 못했던 단점도 있었다

빌드 시간이 살짝 늘었다. 작은 프로젝트라면 체감이 없지만, 파일이 많아지면 tsc가 타입 체킹하는 시간이 쌓인다. transpileOnly 옵션이나 SWC 같은 빠른 트랜스파일러를 쓰면 완화된다.

그리고 제네릭이 복잡해지면 가끔 "이게 맞는 타입인가?" 고민하는 시간이 생긴다. 처음엔 그 시간이 아깝게 느껴졌는데, 지금은 그 고민 자체가 설계를 명확하게 만드는 과정이라는 걸 안다.

마이그레이션 전후 비교

가장 체감되는 건 팀 협업이다. 새로 합류한 팀원이 함수 시그니처만 봐도 뭘 넣고 뭐가 나오는지 바로 파악한다. 문서화 효과가 생각보다 훨씬 크다.

IDE 자동완성도 확실히 달라졌다. VS Code가 뭘 입력할 수 있는지 리스트업해줄 때, 잘못된 타입 넣으면 빨간 줄 긋는 게 진짜 유용하다. 런타임에서 터지던 오류를 코딩 단계에서 잡는다.

시작하는 사람한테 한 마디

겁먹을 필요 없다. 점진적으로 하면 된다. 한 파일씩, 한 모듈씩 바꾸면서 타입 오류를 고쳐나가다 보면 어느 순간 "아, 이게 없던 시절로는 못 돌아가겠다"는 생각이 든다. 그게 TypeScript가 원하는 결과다.

---

📎 참고 자료

• The 8 trends that will define web development in 2026 - LogRocket Blog
• Migrating from JavaScript - TypeScript Official Handbook
• 8 Web Development Trends That Will Define 2026 - Talent500