React 모달이 예상과 다르게 작동할 때 체크리스트

React에서 모달을 만들 때 데스크톱에서는 잘 작동하는데 모바일에서 문제가 생기거나, 열리는데 닫혀야 할 때 닫혀있는 경우가 생긴다. 이런 문제들은 대부분 이벤트 흐름이나 조건 렌더링에서 비롯된다.

문제의 경계 정하기

먼저 문제가 정확히 뭔지 정의한다. 모달이 안 열리는 건지, 열렸는데 안 닫히는 건지, 모바일에서만 문제인지 파악해야 한다.

로컬 개발 환경에서 확인

개발 서버를 실행하고 브라우저 개발자 도구로 모달의 상태를 확인한다.

npm run build
# 브라우저에서 모바일 폭으로 조정하고 테스트

개발자 도구의 Elements 탭에서 모달의 display, visibility, position 속성을 확인한다. 실제로 DOM에 있는지도 본다.

이벤트 흐름 확인

모달을 열고 닫는 이벤트가 제대로 작동하는지 확인한다. onClick, onClose 등의 콜백이 실행되는지 Console에서 로그를 본다.

// 간단한 디버그 로그 추가
console.log('Modal open state:', isOpen);
console.log('Close button clicked');

렌더링 조건 확인

모달이 조건에 따라 렌더링되어야 한다면, 그 조건이 제대로 작동하는지 확인한다. isOpen, isVisible 같은 상태 변수가 제대로 업데이트되는지 본다.

모바일 화면에서 테스트

데스크톱에서는 잘 작동하는데 모바일에서 문제가 나는 경우가 있다. 브라우저의 모바일 에뮬레이션을 사용해서 테스트한다.

• 키보드 입력 흐름 (터치 이벤트와 마우스 이벤트의 차이)
• 뷰포트 높이 (키보드가 나타났을 때 모달이 어떻게 되는지)
• 스크롤 가능성 (모달 내부가 스크롤되는지)

에러 문구 찾기

Console 탭에 에러가 있는지 확인한다. undefined 에러, prop validation 경고 등이 있으면 해결해야 한다.

실패했을 때 다음 후보

1. 모달 컴포넌트의 CSS 클래스 확인 (display: none이 아닌지)
2. 상위 컴포넌트에서 상태 관리가 제대로 되는지 (Redux, Context API)
3. 모달을 감싸는 Portal이나 Provider가 제대로 설정되었는지

작은 수정들을 하나씩 적용하고 결과를 확인하는 게 가장 빠른 방법이다. 나중에 비슷한 문제가 생기면 이 체크리스트를 다시 보고 진행하면 된다.