Back to list
AuthorBYCM Sirius_Alpha··
·1 min read

#04. Vite로 React 프로젝트 생성 + 프로젝트 구조 살펴보기

목차9

TL;DR

  • npm create vite@latest: React 프로젝트 생성
  • Vite = 개발 서버(저장 즉시 화면 반영) + 프로덕션 번들러
  • 핵심 파일들:
    • index.html(순수 HTML)
    • App.jsx(JSX UI 트리)
    • main.jsx (두 항목을 매개)
  • package.json / package-lock.json / eslint.config.js 등의 주변 파일들

개요

React 공부를 시작했으니, 일단 손에 잡히는 프로젝트부터 하나 만들어보자.
이번 글에서는 npm create vite로 프로젝트를 생성하고,
그렇게 만들어진 파일들이 각각 무슨 역할을 하는지 하나씩 정리해보고자 한다.

프로젝트 생성

요즘 React 프로젝트는 Vite로 찍어내는 게 사실상 표준인 듯 하다.
터미널에 아래 한 줄이면 된다.

npm create vite@latest

(위 커맨드 실행을 위해 Node.js가 설치되어있어야 한다.)

  • npm: 각종 Node.js 기반 패키지를 관리하는 패키지 매니저
  • vite: 빌드 도구 + 개발 서버
    • npm run build 시 최종 산출물들을 하나로 묶어준다 (번들링)
    • 파일을 수정하고 저장하면, 별도 새로고침 없이 바로 브라우저 화면에 반영된다

스크린샷 2026-07-23 135702

그러면 터미널이 몇 가지를 물어보는데, 차례대로 고르면 된다.

  • 프로젝트 이름
    • 생성될 폴더 이름이기도 하다.
  • 프레임워크
    • React 뿐 아니라 Vue.js, Svelte 등도 고를 수 있음
  • Variant
    • 어떤 언어(+ 컴파일러)를 쓸 것인가?
    • 이전 글에서 언급했던 React Compiler도 여기 포함된다.
    • React에서는 개발자가 수동으로 최적화해야 했던 부분(Rerender 시 계산을 skip할 부분들)을, 컴파일러가 알아서 줄여준다.
  • Linter
    • 어떤 린트(Lint) 도구를 쓸 것인가?
    • Lint 도구 = 코드를 실행하기 전에 돌리는 정적 검사 도구
    • 무난하게 ESLint를 골랐다.

선택이 끝나고 조금 기다리면 새 프로젝트 폴더가 생성되고, 초기 페이지까지 호스팅해준다.

스크린샷 2026-07-23 135742

브라우저에서 localhost:5173으로 접속하면 아래와 같은 초기 화면을 볼 수 있다.

스크린샷 2026-07-23 135754

프로젝트 구조

스크린샷 2026-07-23 140332

이제 생성된 파일들을 하나씩 살펴보자.

index.html

Single Page Application(SPA)의 진입점이다.
<body> 안에서 JS 스크립트(main.jsx)를 실행한다.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>study_project</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

main.jsx

App 컴포넌트를 실제 화면에 띄우는 단순한 파일이다.

// Import문은 생략

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

그런데 이게 왜 따로 필요할까?

  • index.html은 순수 HTML 파일이라 React를 모름
  • React에서 UI는 JSX(JavaScript XML)로 작성됨
    • 마치 함수가 다른 함수를 호출하는 방식으로 UI 트리가 구성되는데, 이쪽은 DOM의 형태를 모름
  • 서로를 모르는 이 둘을 누군가는 붙여줘야 하는데, 그 중간자 역할을 하는 게 바로 main.jsx

마치 안드로이드 앱 개발에서, Android View 위에 Compose가 그리는 화면 트리를 얹어주는 것과 같다:

class MainActivity : ComponentActivity() {
    override fun onCreate(...) {
        setContent { App() }   // ← 이 setContent가 main.jsx의 createRoot().render()에 대응
    }
}

그리고 Compose가 “단일 Activity 구조(SAA)“를 지향하듯,
React 역시 “Single Page App(SPA)” 구조를 추구한다.

따라서 별도의 요구사항이 없다면 main.jsx와 같은 진입점 파일은 하나면 충분하다.
앱 안에서 여러 페이지 전환이 필요하다면, main.jsx를 늘리는 게 아니라 React Router를 쓰면 된다.

App.jsx

초기 페이지를 그려주는 App() 함수(= 컴포넌트) 하나만 들어있다.

function App() { 
  return (  /* Some HTML */ )
}

export default App
  • 기본으로 함께 생성되는 App.css에서 스타일을 관리한다.
  • 프로젝트를 시작할 때는, return문 안의 내용들과 CSS를 정리하고 내 것으로 채워나가면 된다.

그 외 살펴보면 좋은 파일들

나머지 파일들을 간단하게 표로 정리하자면:

파일역할익숙한 대응
eslint.config.js어떤 규칙(rule)에 따라 경고를 띄울지 설정.
규칙을 추가/조정해 특정 경고를 끌 수도 있다.		detekt / ktlint 설정
package.json프로젝트의 빌드 스크립트, 의존성/모듈 버전을 관리안드로이드의 build.gradle
package-lock.jsonpackage.json을 토대로 실제 설치된 ‘정확한’ 버전을 기록. 다른 환경에서도 동일하게 동작하도록 보장파이썬의 Pipfile.lock
.gitignoregit 관리 시 설치된 모듈/로그/IDE 설정 등을 자동으로 제외git 관리 여부와 상관없이 생성됨

그 외로 vite 설정을 담당하는 vite.config.js 등도 있다.

결론

나중가면 React 프로젝트도 템플릿을 만들어서 돌려쓸 것 같긴 하지만, 우선은 생성 과정과 가장 기초적인 구조는 알아두자는 마인드.
특히 SPA 구조와 main.jsx의 역할은 곱씹어볼 필요가 있어보인다.

링크가 복사되었습니다