Vite로 생성하고 실행하는 기본 흐름을 다룹니다. npm create vite부터 npm run dev, 프로젝트 구조 확인, npm run build, 자주 쓰는 설정까지 초보자가 바로 따라 할 수 있는 순서로 정리했습니다.- Vite는 React에서 무엇을 해주는 도구인가
- React Vite 프로젝트 만들기 전 준비 사항
- Vite로 React 프로젝트 생성하기
- 개발 서버 실행과 화면 확인
- 생성된 프로젝트 구조 이해하기
- React Vite 프로젝트 빌드하기
- 초반에 자주 쓰는 Vite 설정
- 처음 사용할 때 자주 헷갈리는 점
- 정리: Vite는 React 개발 시작점을 단순하게 만든다
Vite는 React에서 무엇을 해주는 도구인가
Vite는 React 코드를 브라우저에서 빠르게 확인하고, 배포 가능한 결과물로 묶어 주는 개발 도구입니다. React 자체는 화면을 컴포넌트로 구성하는 라이브러리이고, Vite는 그 코드를 개발 중에 실행하거나 실제 서비스용 파일로 빌드하는 역할을 맡습니다.
예전에는 React 프로젝트를 시작할 때 Create React App을 많이 사용했습니다. 하지만 프로젝트가 커질수록 개발 서버 시작이나 코드 수정 반영이 느리게 느껴지는 경우가 있었습니다. Vite는 개발 중에는 브라우저가 필요한 모듈만 빠르게 가져가도록 처리하고, 빌드할 때는 최적화된 정적 파일을 만들어 줍니다.
중요한 점은 Vite가 React를 대체하는 도구가 아니라 React 개발 환경을 구성해 주는 도구라는 것입니다. 따라서 useState, useEffect, 컴포넌트 작성 방식은 그대로 사용하면서 프로젝트 생성과 실행 경험만 더 단순하게 가져갈 수 있습니다.
React Vite 프로젝트 만들기 전 준비 사항
Vite로 React 프로젝트를 만들려면 먼저 Node.js와 npm이 설치되어 있어야 합니다. Node.js는 개발 도구를 실행하는 런타임이고, npm은 필요한 패키지를 설치하고 스크립트를 실행하는 패키지 매니저입니다.
node -v
npm -v위 명령어를 실행했을 때 버전 번호가 출력되면 기본 준비는 끝난 상태입니다. 만약 명령어를 찾을 수 없다는 메시지가 나온다면 Node.js를 먼저 설치해야 합니다. 실무에서는 팀마다 npm, pnpm, yarn 중 하나를 정해 쓰기도 하지만, 처음 학습한다면 npm만으로 충분합니다.
npm: 기본으로 설치되어 접근성이 좋습니다.pnpm: 저장 공간과 설치 속도 측면에서 장점이 있습니다.yarn: 기존 프로젝트에서 여전히 자주 만날 수 있습니다.
이 글에서는 가장 범용적인 npm 기준으로 진행합니다. 다른 패키지 매니저를 사용해도 전체 흐름은 거의 같습니다.
Vite로 React 프로젝트 생성하기
새 React 프로젝트는 npm create vite 명령어로 만들 수 있습니다. 터미널에서 프로젝트를 만들 위치로 이동한 뒤 아래 명령어를 실행합니다.
npm create vite@latest my-react-appmy-react-app은 생성할 프로젝트 폴더 이름입니다. 원하는 이름으로 바꿔도 됩니다. 명령어를 실행하면 사용할 프레임워크와 템플릿을 선택하라는 안내가 나옵니다. 여기서는 프레임워크로 React를 선택하고, 템플릿은 일반 JavaScript 기반이라면 JavaScript, 타입 안정성을 함께 가져가고 싶다면 TypeScript를 선택합니다.
처음 React를 익히는 단계라면 JavaScript 템플릿으로 시작해도 좋습니다. 이미 TypeScript를 알고 있거나 실무 프로젝트를 염두에 둔다면 TypeScript 템플릿을 고르는 편이 자연스럽습니다.
cd my-react-app
npm installnpm install은 package.json에 적힌 의존성을 실제로 설치합니다. 이 과정을 거치면 node_modules 폴더가 생기고, 프로젝트에서 필요한 React와 개발 도구가 준비됩니다.
개발 서버 실행과 화면 확인
의존성 설치가 끝나면 개발 서버를 실행할 수 있습니다. Vite 프로젝트에서는 기본적으로 npm run dev를 사용합니다.
npm run dev터미널에 로컬 접속 주소가 표시됩니다. 보통 http://localhost:5173 형태입니다. 브라우저에서 이 주소를 열면 React 기본 화면을 확인할 수 있습니다.
개발 서버가 실행된 상태에서 src/App.jsx를 수정하면 브라우저 화면이 거의 즉시 갱신됩니다. 이 기능은 빠른 피드백을 주기 때문에 컴포넌트 UI를 만들거나 스타일을 조정할 때 체감 차이가 큽니다.
function App() {
return (
<main>
<h1>React Vite 시작하기</h1>
<p>첫 번째 Vite 프로젝트입니다.</p>
</main>
)
}
export default App위처럼 App 컴포넌트를 수정한 뒤 저장하면 새로고침을 직접 누르지 않아도 변경 사항이 반영됩니다. 이 흐름이 Vite를 사용하는 가장 기본적인 개발 경험입니다.
생성된 프로젝트 구조 이해하기
Vite로 프로젝트를 만들면 처음에는 파일이 많아 보일 수 있지만, 핵심은 몇 개뿐입니다. 가장 자주 보는 위치는 src 폴더와 루트의 index.html, vite.config.js, package.json입니다.
my-react-app/
index.html
package.json
vite.config.js
src/
App.jsx
main.jsx
assets/src/main.jsx는 React 앱의 진입점입니다. 여기에서 createRoot를 사용해 App 컴포넌트를 실제 DOM에 연결합니다. src/App.jsx는 기본 화면을 구성하는 컴포넌트 파일이며, 학습 단계에서는 가장 먼저 수정하게 되는 파일입니다.
index.html은 브라우저가 처음 읽는 HTML 파일입니다. 일반 React 코드와 달리 이 파일 안에는 div 같은 실제 루트 요소가 있고, src/main.jsx가 연결됩니다. Vite에서는 index.html도 중요한 진입점으로 취급됩니다.
vite.config.js는 Vite 설정 파일입니다. React 플러그인, 개발 서버 옵션, 경로 별칭 같은 설정을 이 파일에서 다룹니다. 처음에는 거의 수정하지 않아도 되지만, 프로젝트가 커지면 자연스럽게 보게 됩니다.
React Vite 프로젝트 빌드하기
개발 중에는 npm run dev를 사용하지만, 실제 배포를 위해서는 빌드가 필요합니다. 빌드는 개발용 코드를 브라우저가 효율적으로 받을 수 있는 정적 파일로 만드는 과정입니다.
npm run build명령어가 성공하면 dist 폴더가 생성됩니다. 이 폴더 안에는 압축되고 최적화된 HTML, JavaScript, CSS 파일이 들어갑니다. 실제 배포 플랫폼에는 보통 dist 폴더의 결과물이 올라갑니다.
빌드 결과를 로컬에서 확인하고 싶다면 npm run preview를 사용할 수 있습니다.
npm run previewnpm run preview는 개발 서버가 아니라 빌드된 결과물을 미리 보는 서버입니다. 개발 중 화면과 배포용 결과가 다르게 보이는 문제를 확인할 때 유용합니다. 배포 전에는 최소 한 번 npm run build와 npm run preview를 실행해 보는 습관이 좋습니다.
초반에 자주 쓰는 Vite 설정
처음에는 기본 설정만으로 충분하지만, 프로젝트를 진행하다 보면 포트 변경, 자동 브라우저 열기, 경로 별칭 같은 설정이 필요해질 수 있습니다. 이런 설정은 vite.config.js에서 관리합니다.
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
server: {
port: 3000,
open: true
}
})위 설정에서 server.port는 개발 서버 포트를 3000으로 바꿉니다. server.open을 true로 두면 npm run dev 실행 시 브라우저가 자동으로 열립니다.
컴포넌트가 많아지면 상대 경로가 길어질 수 있습니다. 이때는 경로 별칭을 설정해 src 폴더를 짧게 참조할 수 있습니다.
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'node:path'
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
'@': path.resolve(__dirname, './src')
}
}
})이 설정을 적용하면 src/components/Button.jsx를 @/components/Button.jsx처럼 가져올 수 있습니다. 다만 작은 프로젝트에서는 반드시 필요한 설정은 아닙니다. 팀에서 정한 규칙이 없다면 처음에는 기본 상대 경로로 시작하고, 파일 구조가 복잡해질 때 적용해도 늦지 않습니다.
환경 변수는 .env 파일에 작성할 수 있습니다. Vite에서 클라이언트 코드에 노출할 값은 이름이 VITE_로 시작해야 합니다.
VITE_API_BASE_URL=https://api.example.comconst apiBaseUrl = import.meta.env.VITE_API_BASE_URLimport.meta.env는 Vite가 제공하는 환경 변수 접근 방식입니다. 비밀번호나 서버 전용 비밀 키처럼 노출되면 안 되는 값은 프론트엔드 환경 변수에 넣으면 안 됩니다.
처음 사용할 때 자주 헷갈리는 점
첫 번째로 자주 하는 실수는 npm install을 건너뛰는 것입니다. 프로젝트 폴더를 만든 직후 바로 npm run dev를 실행하면 의존성이 없어서 오류가 납니다. 반드시 프로젝트 폴더로 이동한 뒤 npm install을 먼저 실행해야 합니다.
cd my-react-app을 실행하지 않아 다른 위치에서 명령어를 실행하는 경우npm install없이npm run dev를 실행하는 경우localhost주소를 잘못 입력하는 경우.env값을 바꾼 뒤 개발 서버를 재시작하지 않는 경우dist폴더를 직접 수정하려고 하는 경우
dist 폴더는 빌드 결과물이므로 직접 수정하는 대상이 아닙니다. 화면을 바꾸려면 src 안의 React 코드나 스타일 파일을 수정하고 다시 빌드해야 합니다.
또 하나 헷갈리는 부분은 npm run dev와 npm run build의 차이입니다. npm run dev는 개발 중 빠른 확인을 위한 명령어이고, npm run build는 배포 가능한 결과물을 만드는 명령어입니다. 두 명령어는 목적이 다르므로 배포 전에 개발 서버 화면만 보고 끝내지 않는 것이 좋습니다.
정리: Vite는 React 개발 시작점을 단순하게 만든다
Vite를 사용하면 React 프로젝트를 빠르게 만들고, 개발 서버를 실행하고, 수정 결과를 즉시 확인하는 흐름이 단순해집니다. 기본 작업은 npm create vite@latest, npm install, npm run dev, npm run build 네 단계로 이해하면 됩니다.
처음에는 src/App.jsx, src/main.jsx, index.html, vite.config.js의 역할만 알아도 충분합니다. 이후 프로젝트가 커지면 환경 변수, 경로 별칭, 배포 설정을 하나씩 추가하면 됩니다.
Vite의 핵심 가치는 복잡한 설정을 먼저 공부하게 만드는 것이 아니라 React 코드를 빠르게 작성하고 확인할 수 있게 해 주는 데 있습니다. 이 기본 흐름에 익숙해지면 React Router 적용, 상태 관리 도입, API 연동, 배포 같은 다음 단계로 자연스럽게 넘어갈 수 있습니다.