TypeScript optional 타입 추적하기

TypeScript를 쓰다 보면 optional 문제로 몇 시간을 날리는 경험을 많이 한다. 문제는 단순해 보이는데 원인이 어디서 나오는지 찾기가 어렵다는 것. 화면만 봐서는 절대 모르고, 실제 타입이 어떻게 흘러가는지 봐야 한다.

타입 추적의 첫 단계: 환경 정의

문제를 마주했을 때 가장 먼저 해야 할 일은 정상 상태를 정하는 것이다. 로컬에서는 잘 작동하는데 배포 환경에서 타입 에러가 나거나, 런타임에 값이 다르게 들어오는 경우가 많다. 이럴 때는 각 환경을 명확하게 구분해서 확인해야 한다.

먼저 빌드가 통과하는지 확인하자:

npm run build
npx tsc --noEmit

로컬에서는 타입 에러가 없는데 배포 후에만 문제가 생긴다면, 환경 변수나 빌드 설정의 차이를 의심해봐야 한다. 특히 tsconfig.json의 strict 설정이 다르거나, 빌드 타임에 타입이 다르게 해석될 수 있다.

타입 흐름 끊기

optional 문제를 추적할 때는 데이터의 흐름을 선형으로 따라가야 한다. API 응답에서 나온 값 → 컴포넌트로 전달 → 렌더링까지 각 단계에서 타입이 정말로 optional인지 확인해야 한다.

로그와 응답을 함께 봐야 하는 이유가 여기에 있다. 타입 정의는 name?: string인데 실제 응답에서는 항상 값이 들어오거나, 반대로 타입 정의는 필수(name: string)인데 응답에서는 없을 수도 있다. 이런 불일치를 찾아야 한다.

타입 가드 점검

타입 가드가 제대로 작동하지 않으면 optional 추적이 복잡해진다. 만약 다음과 같은 코드가 있다면:

if (user && user.profile) {
  console.log(user.profile.name);
}

TypeScript는 if 블록 내에서 user.profile.name이 안전하다고 판단한다. 하지만 user는 정의되었지만 profile이 없을 수 있다면 타입 에러가 난다. 이 경우 타입 정의를 다시 확인해야 한다.

실제 확인 순서

1. 원래 증상이 같은 조건에서 다시 나오는지 재현해본다. 간헐적인 에러라면 더 까다롭다.
2. 빌드 로그와 런타임 에러 메시지를 함께 본다. 타입 에러와 런타임 에러는 다를 수 있다.
3. 공개 URL에서 실제 응답을 확인한다. 브라우저 개발자 도구의 Network 탭에서 API 응답을 보면 타입과 실제 데이터의 차이를 명확히 알 수 있다.

기록 남기기

나중에 비슷한 문제가 나올 때를 대비해서 작은 것이라도 기록해두면 훨씬 빠르게 처리할 수 있다. 무엇이 바뀌었는지, 왜 바뀌었는지를 한 줄로 정리해두면 다음 추적이 한결 수월하다.