🚨 PropTypes에서 JSDoc으로 — React 19 타입 관리 트러블슈팅

🔗 프로젝트 - 롤링

1. 🚨 Tailwind + cva + clsx + twMerge 조합에서 커스텀 유틸리티가 적용되지 않을 때

2. 🚨 PropTypes에서 JSDoc으로 — React 19 타입 관리 트러블슈팅

3. 🚨 낙관적 업데이트 — 이모지 반응 UI 미반영 트러블슈팅

4. [코드잇 스프린트 FE 19기] 기초 프로젝트 - 롤링 회고

---

1️⃣ 문제 상황

자바스크립트를 사용하는 프로젝트여서

컴포넌트의 props 타입을 명시하기 위해 팀에서 PropTypes를 사용해보기로 결정했다.

 

import PropTypes from 'prop-types';

const Button = ({ label, onClick }) => {
  return <button onClick={onClick}>{label}</button>;
};

Button.propTypes = {
  label: PropTypes.string.isRequired, // 문자열이어야 하고 필수
  onClick: PropTypes.func,            // 함수
};

export default Button;

PropTypes를 사용하면 개발 환경(dev)에서 타입 검증을 수행하고,

잘못된 props가 전달될 경우 콘솔에 경고를 출력해주기 때문에

자바스크립트에서도 일정 수준의 타입 안정성을 챙길 수 있는 장점이 있다.

 

너무나도 깨끗한 콘솔창.....

그러나 예상과는 달리 개발 환경에서 테스트해보니,

잘못된 props를 전달해도 콘솔에 경고가 발생하지 않는 문제가 발견되었다.

 

2️⃣ 원인 분석

처음에는 PropTypes 설정이 잘못되었나 싶어 패키지를 재설치해보고,

ESLint 설정을 수정해보는 등 여러 방법을 시도하였다.

이렇게 해도 안되고, 저렇게 해도 안되길래 설마..?하면서 리액트 공식문서를 찾아봤다.

리액트 공식 문서를 확인해본 결과,

React 19부터는 PropTypes가 더 이상 지원되지 않는다는 사실을 알게 되었다. (거짓말이라 해줘...)

 

이를 확인하기 위해 React 18 환경을 별도로 구성해서 테스트 해보니

이전 버전에서는 정상적으로 콘솔 경고가 출력되는 것을 확인할 수 있었다.......🤦‍♀️

 

3️⃣ 해결 방법

React 19에서는 PropTypes를 더 이상 사용할 수 없기 때문에

차선책으로 JSDoc 주석을 사용한 props 타입 정의 방식을 선택하였다.

/**
 * @param {Object} props
 * @param {string} props.label - 버튼에 표시할 텍스트
 * @param {() => void} [props.onClick] - 클릭 이벤트 핸들러
 */
const Button = ({ label, onClick }) => {
  return <button onClick={onClick}>{label}</button>;
};

JSDoc을 작성하면 VScode에서 자동완성 기능을 지원받을 수 있어서 편리했고,

팀원이 만든 컴포넌트를 이해하는데에도 도움되었다.

 

다만 JSDoc은 정적 타입 검사를 해주진 않아서

PropTypes처럼 런타임 에러를 잡아주지는 않는다.

 

따라서 타입 안정성을 확보하기 위해

다음 프로젝트에서는 TypeScript를 도입하는 것이 가장 확실한 방법이라고 생각했다.

 

4️⃣ 정리

• React 19부터는 prop-types가 자동으로 무시되어 작동하지 않는다.
  • PropTypes를 잘 적용했는데 아무런 경고가 뜨지 않는다면 리액트 버전을 확인해보자
  • 공식문서를 자주 확인하자...🥲
• Prop Types를 이용한 런타임 타입 검증이 필요한 경우 React 18 이하 버전을 사용해야 한다.
• React 19에서는 JSDoc으로 대체하거나, 장기적으로 TypeScript를 도입하는 것이 가장 안정적이다.