TypeScript 타입 에러를 빠르게 찾아내는 체크리스트

TypeScript를 사용하면서 가장 자주 마주치는 문제는 "타입이 맞는데도 에러가 난다"는 상황이다. 문제를 크게 잡으면 모든 파일이 의심스러워져서 수정하기 어려워진다. 따라서 원인을 좁혀가는 순서가 중요하다.

먼저 빌드 에러를 정리한다

TypeScript 컴파일러의 에러 메시지는 보통 직관적이다. 어느 파일의 몇 번째 줄에서 어떤 타입이 예상되는데 다른 타입이 들어왔는지 명확하게 알려준다.

npm run build
npx tsc --noEmit

두 번째 명령어는 JavaScript 파일을 생성하지 않고 타입 체크만 수행하므로, 에러 메시지를 빠르게 확인할 수 있다.

Optional과 null을 헷갈리지 않는다

자주 실수하는 부분이 optional 프로퍼티(user?.name)와 null/undefined 타입(name: string | null)의 차이다. 타입 가드를 제대로 써야 에러가 줄어든다.

타입 정의를 다시 읽어본다

만들어진 지 오래된 타입 정의는 실제 데이터 구조와 맞지 않을 수 있다. API 응답이 변경되었거나, 함수의 반환값이 예상과 다를 수 있다. 타입 정의 파일을 열어서 실제 데이터와 비교하는 단계가 필수다.

타입 안정성을 완전히 켠다

tsconfig.json에서 strict: true를 확인하고, 필요하면 noImplicitAny: true, strictNullChecks: true 같은 옵션을 추가한다. 처음엔 에러가 많아 보이지만, 장기적으로 버그를 줄이는 데 도움이 된다.

한 단계씩 테스트한다

TypeScript 에러를 수정할 때는 한 함수, 한 컴포넌트씩 격리해서 테스트하는 게 좋다. 여러 타입 변경을 동시에 하면 어디서 문제가 생겼는지 알기 어렵다.

타입 에러를 무시하고 진행하면 나중에 런타임에서 훨씬 복잡한 버그가 터진다. 컴파일 시간에 작은 불편을 감수하면, 운영 환경에서의 사고를 줄일 수 있다.