React 컴포넌트에 들어오는 데이터 타입이 예상과 다를 때

런타임 타입 불일치는 타입스크립트를 써도 자주 마주친다. 보통 API 응답이 예상과 다르거나, 부모 컴포넌트에서 잘못된 형태로 넘어올 때다. 빠르게 원인을 좁히려면 확인 순서가 중요하다.

먼저 렌더링 조건 확인하기

컴포넌트가 실제로 어떤 props를 받고 있는지 먼저 본다. 개발자 도구의 React 탭에서 해당 컴포넌트를 선택하면 현재 props를 바로 볼 수 있다. console.log로도 충분하지만, 정상 상태와 비교하려면 Redux DevTools나 컴포넌트 상태 스냅샷이 도움이 된다.

브라우저에서 실제 요청 추적

Network 탭에서 API 응답을 확인한다. 백엔드에서 보낸 데이터가 실제로 어떤 형태인지 직접 본다.

# 혹은 curl로 로컬에서도 확인 가능
curl -s http://localhost:3000/api/data | jq '.'

데이터 구조가 타입 정의와 다르면, props 변환 로직이 필요한지 컴포넌트에서 미리 파싱해야 하는지 판단한다.

컴포넌트 내부의 타입 가드 추가

타입스크립트의 타입 좁히기(type narrowing)를 활용해서, 런타임에 실제 데이터 형태를 확인한다.

interface Props {
  user: { id: string; name: string } | null;
}

function MyComponent({ user }: Props) {
  if (!user || typeof user !== 'object') {
    return <div>Invalid user data</div>;
  }

  if (!('id' in user) || !('name' in user)) {
    console.warn('User object missing expected fields', user);
  }

  return <div>{user.name}</div>;
}

모바일 환경과 프로덕션 환경 구분

로컬에서는 정상이지만 배포 환경에서만 문제가 나는 경우가 많다. 빌드 결과와 환경 변수를 함께 확인한다.

npm run build
npm run start  # 프로덕션 빌드로 로컬 테스트

SSR이 있다면 서버에서 넘어오는 초기 데이터 형태를 따로 검증해야 한다.

마지막 확인: 실제 사용자 흐름

증상이 재현되는 경우를 찾아서, 로그와 네트워크 응답을 함께 기록한다. "어느 API 엔드포인트에서 이 형태로 왔다"는 식으로 한 줄로 설명할 수 있으면 원인 추적이 훨씬 빨라진다. 다음에 비슷한 문제가 나왔을 때 기록해둔 환경 정보가 큰 도움이 된다.