Vite로 생성한 React 프로젝트의 폴더 구조 살펴보기

Vite가 자동으로 만들어주는 폴더와 파일들, 각각 어떤 역할을 하는지 하나씩 짚어봅니다.

---

들어가며

앞서 Vite를 사용해 React 초기 프로젝트를 생성해 보았습니다. Vite는 복잡한 TypeScript 설정까지 자동으로 처리해주기 때문에 새로운 React 프로젝트를 만들 때 매우 유용한 도구입니다.

프로젝트를 생성하면 기본적인 폴더 구조와 파일들이 자동으로 만들어지는데, 이번 글에서는 이 폴더와 파일들이 각각 어떤 의미를 가지는지 살펴보겠습니다.

---

전체 폴더 구조 한눈에 보기

my-react-app/
├── node_modules/
├── public/
├── src/
│   ├── assets/
│   ├── App.css
│   ├── App.tsx
│   ├── index.css
│   ├── main.tsx
│   └── vite-env.d.ts
├── .gitignore
├── eslint.config.js
├── index.html
├── package.json
├── package-lock.json
├── README.md
├── tsconfig.json
├── tsconfig.app.json
└── tsconfig.node.json

---

폴더별 설명

node_modules/

npm이나 Yarn 같은 패키지 매니저를 통해 설치된 라이브러리들이 전부 모여있는 폴더입니다. React, TypeScript 라이브러리, 그리고 프로젝트에서 사용하는 모든 외부 모듈이 여기에 저장됩니다.

용량이 매우 커지기 때문에 .gitignore 파일에 추가하여 버전 관리 대상에서 제외하는 것이 일반적입니다.

public/

이미지, 폰트, 파비콘 등 정적 리소스를 저장하는 공간입니다. Vite로 프로젝트를 빌드할 때 이 폴더의 파일들은 별도의 변환 없이 그대로 복사되어 최종 애플리케이션에 포함됩니다.

추가적인 번들 작업이 필요 없는 리소스를 보관하기에 적합합니다.

src/

프로젝트의 핵심 코드가 모두 들어있는 폴더입니다. 실제로 작성할 React 컴포넌트, TypeScript 코드, 스타일 파일 등이 이곳에 위치합니다.

---

src/ 내부 파일 상세

assets/

이미지나 아이콘처럼 컴포넌트에서 사용하는 별도의 리소스들을 정리하는 폴더입니다. public/ 폴더와 달리, 이곳의 파일들은 빌드 과정에서 번들러에 의해 처리됩니다.

App.css / index.css

App.css는 App 컴포넌트에 적용되는 스타일, index.css는 전역 스타일을 정의하는 파일입니다. 컴포넌트별 스타일과 전역 스타일을 분리하여 관리할 수 있습니다.

App.tsx

애플리케이션의 루트 컴포넌트를 정의하는 파일입니다. 화면에 렌더링되는 UI의 시작점이라고 할 수 있습니다.

main.tsx

createRoot 함수를 사용하여 App 컴포넌트를 DOM에 실제로 렌더링하는 진입점 파일입니다. index.html의 특정 DOM 요소에 React 앱을 마운트하는 역할을 합니다.

vite-env.d.ts

초기에는 아무 코드도 없지만, Vite 환경에서 필요한 타입 선언을 처리해 주는 파일입니다. TypeScript 코드가 Vite 환경에서 원활히 동작할 수 있도록 도와줍니다.

---

루트 디렉토리 파일 상세

.gitignore

Git으로 버전 관리를 할 때 추적하지 않을 폴더나 파일을 지정하는 설정 파일입니다. 일반적으로 node_modules/ 폴더나 빌드 결과물이 저장되는 dist/ 폴더 등을 여기에 명시하여 관리 대상에서 제외합니다.

eslint.config.js

프로젝트 전체에서 일관된 코딩 스타일과 품질을 유지하기 위해 ESLint를 설정하는 파일입니다. 코드를 검사하는 규칙, 플러그인, 환경 설정 등을 정의합니다.

index.html

싱글 페이지 애플리케이션(SPA) 구조에서 가장 처음 로드되는 HTML 파일입니다. React는 이 HTML 파일의 특정 DOM 요소에 렌더링되는 방식으로 화면을 구성합니다. 빌드 과정에서 필요한 스크립트와 스타일이 자동으로 삽입되므로, 프로젝트의 최초 진입점이라고 생각하면 됩니다.

package.json

프로젝트의 이름, 버전, 스크립트, 종속 패키지 목록(dependencies, devDependencies) 등을 관리하는 파일입니다. 여기에 명시된 패키지들이 npm install 시 설치됩니다.

package-lock.json

package.json에 명시된 패키지의 정확한 버전과 구조를 기록하는 파일입니다.

package.json에서 버전을 ^19.0.3처럼 지정하면, 이는 "19.0.3 이상의 호환 버전이면 된다"는 의미입니다. 따라서 npm install을 실행할 때마다 실제 설치되는 버전이 달라질 수 있습니다. package-lock.json은 이때 실제로 설치된 구체적인 버전을 고정하여, 누가 어디서 설치하더라도 동일한 환경을 보장해 줍니다.

💡 정리하면

• package.json → 설치하고자 하는 패키지와 버전 범위를 명시
• package-lock.json → 실제 설치된 정확한 버전을 기록

README.md

프로젝트에 대한 개요, 설치 방법, 사용법, 주의사항 등을 문서화하는 파일입니다. 협업을 하거나 오픈소스로 공개할 때 반드시 필요한 정보들을 정리해 둡니다.

tsconfig.json / tsconfig.app.json / tsconfig.node.json

TypeScript가 코드를 어떻게 해석하고 컴파일할지 정의하는 설정 파일들입니다. 각 파일은 적용 범위에 따라 분리되어 있습니다.

파일 적용 범위

tsconfig.json	프로젝트 전체 기본 설정
tsconfig.app.json	React 애플리케이션(브라우저) 환경 설정
tsconfig.node.json	Node.js 환경(Vite 설정 파일 등) 설정

이렇게 환경별로 설정을 분리하면, 브라우저용 코드와 빌드 도구용 코드에 각각 최적화된 TypeScript 설정을 적용할 수 있습니다.

---

마무리

Vite가 생성하는 프로젝트 구조는 간결하면서도 실무에서 바로 사용할 수 있도록 잘 정리되어 있습니다. 각 파일과 폴더의 역할을 이해해 두면 프로젝트를 확장하거나 커스터마이징할 때 훨씬 수월하게 작업할 수 있습니다.