React 개발 서버는 켜졌는데 화면은 하얗다: Console로 원인 찾기

React 개발 서버가 켜졌는데 브라우저가 하얗게 비면 초보자는 보통 두 가지를 헷갈린다. 서버가 안 뜬 것인지, React 코드가 렌더링 중에 멈춘 것인지다. 터미널에 ready가 보여도 화면은 비어 있을 수 있다. 이때 AI에게 "화면이 안 나와요"라고만 물으면 답은 길어지고, 파일은 더 많이 바뀐다.

먼저 원인의 갈래부터 나눈다. 목표는 바로 고치는 것이 아니라, AI에게 줄 증거를 모으는 것이다. 브라우저 콘솔 첫 줄, 화면을 그리는 컴포넌트, 마지막으로 바꾼 코드를 잡으면 하얀 화면의 원인 후보를 훨씬 작게 만들 수 있다.

Tap to zoom

먼저 브라우저 콘솔 첫 줄만 본다

하얀 화면에서 가장 먼저 볼 곳은 터미널이 아니라 브라우저 콘솔이다. Chrome 기준으로 F12를 누르고 Console 탭을 연다. 여기서 빨간 줄이 여러 개 보여도 처음부터 전부 읽지 않는다. 첫 번째 빨간 오류 한 줄만 복사한다.

예를 들어 이런 문장이 보일 수 있다.

Cannot read properties of undefined

Element type is invalid

ReferenceError: Button is not defined

MDN은 null이나 undefined에서 속성을 읽으려 할 때 TypeError가 난다고 설명한다. React 화면이 하얗게 비는 초보자 문제에서도 이 패턴이 자주 나온다. 데이터가 아직 오지 않았는데 user.name을 바로 읽거나, 배열이 아닌 값에 .map()을 붙이는 식이다.

콘솔이 비어 있다면 다음 단계로 넘어간다. 콘솔이 비어 있다는 것도 중요한 증거다. AI에게는 "콘솔 오류 없음"이라고 적어야 한다.

Tap to zoom

root가 실제로 붙는지 확인한다

React는 보통 HTML의 한 요소에 앱을 붙인다. Vite나 일반 React 프로젝트라면 index.html에 이런 요소가 있다.

<div id="root"></div>

그리고 main.jsx 또는 main.tsx에서 비슷한 코드가 있다.

createRoot(document.getElementById("root")).render(<App />);

여기서 id가 다르면 앱은 붙을 곳을 못 찾는다. 예를 들어 HTML은 id="app"인데 코드가 "root"를 찾으면 화면이 비거나 오류가 난다. AI에게 수정 요청을 하기 전에 index.html의 id와 main.tsx의 id가 같은지만 확인한다.

초보자에게 중요한 기준은 이렇다. 하얀 화면인데 콘솔에 root 관련 오류가 있으면 디자인 문제가 아니라 시작점 문제다. CSS나 색상부터 고치지 않는다.

return null과 조건문을 찾는다

React 공식 문서는 조건에 따라 아무것도 렌더링하지 않을 때 컴포넌트가 null을 반환할 수 있다고 설명한다. 이 기능 자체는 정상이다. 문제는 초보자가 로딩 처리나 로그인 조건을 만들다가 모든 경우에 null이 되게 만드는 순간이다.

이런 코드를 확인한다.

function App() {
  if (!user) return null;

  return <Dashboard user={user} />;
}

user가 아직 준비되지 않았다면 화면은 정상적으로 비어 있다. 오류가 아니라 "아무것도 그리지 말라"는 코드가 실행된 것이다. 이때는 최소한 로딩 문구를 넣어서 렌더링 경로를 확인한다.

function App() {
  if (!user) return <p>사용자 정보를 불러오는 중입니다.</p>;

  return <Dashboard user={user} />;
}

AI에게는 이렇게 묻는 편이 낫다.

React 화면이 하얗게 비어 있습니다.
Console 첫 오류: 없음
App.tsx에서 if (!user) return null 코드가 있습니다.
이 조건 때문에 전체 화면이 비는지 확인하고, 최소 수정으로 로딩 문구가 보이게 바꿔 주세요.

이 프롬프트는 "전체 앱을 다시 짜줘"가 아니다. 하얀 화면을 만드는 조건 하나만 확인해 달라는 요청이다.

데이터가 오기 전에 .map()이나 .name을 읽는지 본다

하얀 화면의 흔한 원인은 데이터 접근이다. API 응답이 오기 전에는 값이 비어 있을 수 있다. 그런데 코드가 바로 속성을 읽으면 렌더링 중 오류가 나고 화면이 사라진다.

문제 예시는 이렇다.

export function UserCard({ user }) {
  return <h2>{user.name}</h2>;
}

user가 잠깐 undefined라면 위 코드는 실패한다. 점검용으로는 먼저 방어 코드를 넣어 화면이 살아나는지 본다.

export function UserCard({ user }) {
  if (!user) return <p>사용자 정보가 없습니다.</p>;

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

배열도 같다.

{items.map((item) => (
  <li key={item.id}>{item.title}</li>
))}

items가 배열인지 확실하지 않다면 처음에는 이렇게 좁힌다.

{Array.isArray(items) && items.map((item) => (
  <li key={item.id}>{item.title}</li>
))}

이 코드는 최종 설계가 아니라 진단용이다. 화면이 살아나면 원인은 스타일이 아니라 데이터 준비 순서였다는 뜻이다. 그다음에 로딩 상태, 빈 상태, 오류 상태를 따로 정리하면 된다.

마지막으로 바꾼 import 한 줄을 확인한다

콘솔에 Element type is invalid 같은 문장이 나오면 컴포넌트를 잘못 가져왔을 가능성이 있다. 초보자에게는 default export와 named export 차이가 특히 자주 걸린다.

예를 들어 파일이 이렇게 내보낸다면:

export function Header() {
  return <header>코딩사관학교</header>;
}

가져올 때는 중괄호가 필요하다.

import { Header } from "./Header";

반대로 파일이 이렇게 내보낸다면:

export default function Header() {
  return <header>코딩사관학교</header>;
}

가져올 때는 중괄호를 쓰지 않는다.

import Header from "./Header";

하얀 화면이 갑자기 생겼다면 마지막으로 추가한 컴포넌트 import부터 본다. AI에게도 "방금 추가한 import는 이 줄입니다"라고 붙여 넣는다. 그러면 AI가 전체 구조를 추측하지 않고 바로 한 줄을 비교할 수 있다.

저장, 재시작, 강력 새로고침을 한 번만 한다

코드를 고쳤는데도 화면이 그대로라면 확인 순서는 세 개다.

1. 파일 저장이 됐는지 본다.
2. 개발 서버를 한 번 끄고 다시 켠다.
3. 브라우저에서 강력 새로고침을 한다.

여기서 계속 새로고침만 반복하면 시간을 잃는다. 재시작 후에도 같은 첫 오류가 나오면 코드 문제로 돌아간다. 반대로 오류가 바뀌면 원인에 가까워진 것이다. 바뀐 오류를 새 증거로 삼는다.

Tap to zoom

AI에게 붙여 넣을 최종 프롬프트

아래 형식으로 붙여 넣으면 답이 짧아지고 수정 범위가 줄어든다.

React 개발 서버는 켜졌지만
브라우저 화면이 하얗게 비어 있습니다.

상황:
- 실행 명령: npm run dev
- 브라우저 URL:
  http://localhost:5173
- Console 첫 오류:
  여기에 첫 번째 빨간 줄 붙여넣기
- 콘솔 오류가 없으면: "콘솔 오류 없음"
- 마지막으로 바꾼 파일: src/App.tsx
- 마지막으로 바꾼 코드:
  여기에 코드 10~30줄 붙여넣기

요청:
전체 앱을 다시 만들지 말고,
하얀 화면을 만드는 원인 후보를
3개 이하로 좁혀 주세요.
먼저 확인할 파일과
최소 수정 코드만 제안해 주세요.

이 프롬프트의 핵심은 "전체 재작성 금지"다. AI 코딩 초보자는 막히면 큰 요청을 하기 쉽다. 하지만 하얀 화면은 큰 요청보다 작은 증거가 더 빨리 해결한다.

오늘의 결론

React 하얀 화면은 무조건 어려운 오류가 아니다. 브라우저 콘솔 첫 줄, root 마운트, return null, 데이터 접근, import/export를 순서대로 보면 원인이 작아진다.

콘솔에 Module not found가 보인다면 이 글의 범위를 벗어난 경우다. 그때는 오류 뒤의 이름부터 구분하는 React 모듈 점검법으로 이어가면 된다. 화면은 보이지만 입력이나 선택값만 갱신되지 않는다면 React select의 value부터 확인하는 순서가 더 가깝다.

오늘 바로 할 일은 하나다. 하얀 화면을 본 순간 새 강의나 전체 재작성을 찾지 말고, 첫 오류 한 줄과 마지막 수정 코드부터 저장한다. 그 두 가지가 있으면 AI는 추측보다 확인에 가까운 답을 낼 수 있다.

참고한 공식 문서

• React 공식 문서, Component reference: Error Boundary로 렌더링 오류 처리
• React 공식 문서, createRoot: 브라우저 DOM 노드에 React 앱 렌더링
• React 공식 문서, Conditional Rendering: 조건에 따라 null 반환
• MDN JavaScript error reference: null 또는 undefined 속성 접근 TypeError
• Vite 공식 문서: index.html과 프로젝트 루트

도구 버전과 동작은 바뀔 수 있으므로 적용 전 공식 문서와 최신 릴리스 노트를 확인하세요.