3강. React 프로젝트 구조와 실행 흐름

?1. 이번 강의에서 해결할 문제

프로젝트는 실행되지만 index.html, main.tsx, App.tsx가 어떻게 이어지는지 모르면 오류가 난 파일을 찾기 어렵습니다. 기본 예제를 정리하며 실행 흐름을 확인합니다.

✓2. 학습 목표

• Vite 프로젝트의 핵심 파일 역할을 구분한다.
• index.html에서 App 컴포넌트까지의 흐름을 설명한다.
• 기본 예제를 대시보드 시작 화면으로 교체한다.

◇3. 핵심 개념

Vite에서는 루트의 index.html이 시작점입니다. 이 문서가 src/main.tsx 모듈을 불러오고, main.tsx가 React 루트를 생성해 App을 렌더링합니다.

public은 주소 그대로 제공할 정적 파일, src는 빌드 과정에서 처리할 소스 파일을 둡니다. JSX가 들어간 TypeScript 파일은 .tsx, 일반 TypeScript 파일은 .ts를 사용합니다.

</>4. 단계별 코드 예시

파일 경로: game-release-dashboard/src/App.tsx

import './App.css';

function App() {
  return (
    <main className="app">
      <p className="eyebrow">GAME RELEASE DASHBOARD</p>
      <h1>다음에 즐길 게임을 발견하세요</h1>
      <p>출시 일정과 커뮤니티 랭킹을 한곳에서 확인합니다.</p>
    </main>
  );
}

export default App;

파일 경로: game-release-dashboard/src/App.css

.app {
  width: min(70rem, calc(100% - 2rem));
  margin: 0 auto;
  padding: 4rem 0;
}

.eyebrow {
  color: #7c3aed;
  font-weight: 700;
}

파일 경로: game-release-dashboard/src/main.tsx

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './index.css';
import App from './App.tsx';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

→5. 코드가 동작하는 이유

index.html의 div#root가 React가 관리할 경계입니다. createRoot가 그 요소에 연결되고 App의 반환값을 DOM으로 만듭니다. import한 CSS는 Vite가 모듈 그래프에 포함해 페이지에 적용합니다.

!6. 자주 하는 실수와 해결법

• root id 변경 후 main.tsx를 그대로 둠: index.html과 getElementById 값을 맞춥니다.
• 파일명 대소문자 불일치: Windows에서는 보여도 배포 서버에서 실패할 수 있으므로 import와 실제 이름을 정확히 맞춥니다.
• 느낌표를 무조건 사용: 여기서는 템플릿에 root가 반드시 있어 사용하지만, 일반 DOM 탐색에서는 null 검사부터 합니다.

✎7. 직접 실습

Vite 로고와 카운터 코드를 제거하고 위 시작 화면으로 바꾸세요. 브라우저 개발자 도구의 Elements에서 div#root 안에 main이 생성됐는지 확인하세요.

?8. 이해 점검 질문 3개

1. 브라우저가 처음 읽는 프로젝트 파일은 무엇인가요?
2. main.tsx와 App.tsx의 책임은 어떻게 다른가요?
3. JSX가 들어간 파일에 .tsx 확장자가 필요한 이유는 무엇인가요?

■9. 핵심 요약

index.html → main.tsx → App.tsx 순서로 UI가 시작됩니다. 실행 흐름을 알면 흰 화면이나 import 오류를 어느 계층에서 찾아야 할지 판단할 수 있습니다.