GWCoding HOME
Tech Stack/React

[React] 02. Vite로 React 개발환경 만들기

2026. 5. 21. 09:58

[React] 02. Vite로 React 개발환경 만들기

이전 글에서는 React가 무엇인지, 왜 웹 개발에서 많이 사용되는지 알아보았습니다. 이번 글에서는 React 코드를 직접 작성하고 실행할 수 있도록 Vite를 이용해 React 개발환경을 만드는 방법을 정리해보겠습니다.

React는 브라우저에서 바로 실행하는 단순 HTML 파일과는 다르게, 프로젝트를 구성하고 개발 서버를 실행하는 과정이 필요합니다. 처음에는 낯설 수 있지만, 한 번만 흐름을 이해하면 이후 프로젝트를 만들 때 훨씬 편해집니다.

1. Vite란?

Vite는 프론트엔드 프로젝트를 빠르게 만들고 실행할 수 있게 도와주는 빌드 도구입니다. React 프로젝트를 만들 때 필요한 기본 구조를 자동으로 만들어주고, 개발 중에는 브라우저에서 바로 결과를 확인할 수 있는 개발 서버도 제공합니다.

예전에는 React 프로젝트를 만들 때 Create React App을 많이 사용했지만, 요즘은 더 빠르고 가벼운 Vite를 사용하는 경우가 많습니다.

Vite를 사용하면 다음과 같은 장점이 있습니다.

  • React 프로젝트를 빠르게 생성할 수 있습니다.
  • 개발 서버 실행 속도가 빠릅니다.
  • 코드를 수정하면 브라우저 화면에 빠르게 반영됩니다.
  • 기본 프로젝트 구조가 깔끔합니다.

2. React 개발환경을 만들기 전에 필요한 것

React 프로젝트를 만들기 위해서는 먼저 Node.js가 설치되어 있어야 합니다. Node.js를 설치하면 npm도 함께 설치됩니다.

여기서 npm은 JavaScript 라이브러리와 패키지를 설치하고 관리하는 도구입니다. React 프로젝트를 만들고 실행할 때 npm 명령어를 사용하게 됩니다.

설치가 되어 있는지 확인하려면 터미널 또는 명령 프롬프트에서 아래 명령어를 입력합니다.


node -v
npm -v

정상적으로 설치되어 있다면 다음과 같이 버전 정보가 출력됩니다.


v22.12.0
10.9.0

버전 숫자는 컴퓨터마다 다를 수 있습니다. 중요한 것은 node -v와 npm -v를 입력했을 때 오류가 아니라 버전이 나와야 한다는 점입니다.

3. React 프로젝트 생성하기

이제 Vite를 이용해 React 프로젝트를 만들어보겠습니다. 원하는 폴더 위치에서 터미널을 열고 아래 명령어를 입력합니다.


npm create vite@latest my-react-app -- --template react

위 명령어의 의미는 다음과 같습니다.

  • npm create vite@latest : 최신 Vite 프로젝트 생성 도구를 실행합니다.
  • my-react-app : 생성할 프로젝트 폴더 이름입니다.
  • --template react : React 템플릿으로 프로젝트를 만들겠다는 의미입니다.

프로젝트 이름은 원하는 이름으로 바꿀 수 있습니다. 예를 들어 react-study라는 이름으로 만들고 싶다면 아래처럼 작성하면 됩니다.


npm create vite@latest react-study -- --template react

4. 프로젝트 폴더로 이동하기

프로젝트가 생성되었다면 해당 폴더로 이동해야 합니다.


cd my-react-app

cd는 change directory의 줄임말로, 현재 터미널 위치를 해당 폴더로 이동시키는 명령어입니다.

프로젝트 이름을 react-study로 만들었다면 아래처럼 이동하면 됩니다.


cd react-study

5. 필요한 패키지 설치하기

Vite로 프로젝트를 생성하면 기본 설정 파일은 만들어지지만, 실제로 실행에 필요한 패키지들은 아직 설치되지 않은 상태입니다. 그래서 프로젝트 폴더 안에서 아래 명령어를 실행해야 합니다.


npm install

이 명령어를 실행하면 package.json 파일에 적혀 있는 패키지들이 설치됩니다. 설치가 완료되면 프로젝트 폴더 안에 node_modules 폴더가 생성됩니다.

node_modules 폴더는 프로젝트에서 사용하는 라이브러리들이 들어 있는 폴더입니다. 용량이 크기 때문에 보통 GitHub에 올릴 때는 제외합니다.

6. React 개발 서버 실행하기

패키지 설치가 끝났다면 이제 React 프로젝트를 실행해보겠습니다.


npm run dev

명령어를 실행하면 터미널에 아래와 비슷한 내용이 출력됩니다.


Local:   http://localhost:5173/

브라우저에서 해당 주소로 접속하면 React 기본 화면을 확인할 수 있습니다. 보통 주소는 http://localhost:5173/으로 실행됩니다.

여기서 localhost는 내 컴퓨터 안에서 실행 중인 서버를 의미합니다. 즉, 아직 인터넷에 배포된 사이트가 아니라 내 컴퓨터에서만 확인할 수 있는 개발용 주소입니다.

7. 프로젝트 폴더 구조 살펴보기

Vite로 React 프로젝트를 생성하면 대략 다음과 같은 구조가 만들어집니다.


my-react-app
├─ node_modules
├─ public
├─ src
│  ├─ assets
│  ├─ App.css
│  ├─ App.jsx
│  ├─ index.css
│  └─ main.jsx
├─ index.html
├─ package.json
└─ vite.config.js

처음에는 파일이 많아 보일 수 있지만, React를 공부할 때 주로 보게 되는 파일은 src 폴더 안에 있습니다.

1) src 폴더

src는 source의 줄임말입니다. React 컴포넌트와 CSS 파일 등 실제 개발 코드가 들어가는 폴더입니다.

2) main.jsx

main.jsx는 React 앱의 시작 지점입니다. 이 파일에서 React 화면을 HTML 문서의 특정 위치에 연결합니다.


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

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

여기서 중요한 부분은 <App />입니다. React는 App 컴포넌트를 기준으로 화면을 구성합니다.

3) App.jsx

App.jsx는 기본 화면을 담당하는 컴포넌트 파일입니다. 처음 React를 공부할 때 가장 많이 수정하게 되는 파일입니다.

기본 코드를 모두 지우고 아래처럼 간단하게 바꿔볼 수 있습니다.


function App() {
  return (
    <div>
      <h1>React 시작하기</h1>
      <p>Vite로 만든 첫 번째 React 프로젝트입니다.</p>
    </div>
  );
}

export default App;

저장하면 브라우저 화면이 자동으로 변경되는 것을 확인할 수 있습니다. 이처럼 Vite 개발 서버는 코드를 수정했을 때 변경 사항을 빠르게 반영해줍니다.

4) package.json

package.json은 프로젝트의 정보와 실행 명령어, 설치된 패키지 정보를 관리하는 파일입니다.


{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

여기서 npm run dev를 실행하면 내부적으로 vite 명령어가 실행됩니다.

8. 개발 서버 종료하기

React 개발 서버를 종료하려면 터미널에서 아래 키를 누르면 됩니다.


Ctrl + C

종료할지 묻는 문구가 나오면 Y를 입력하고 Enter를 누르면 됩니다.

다시 실행하고 싶다면 프로젝트 폴더 안에서 아래 명령어를 입력하면 됩니다.


npm run dev

9. 자주 발생하는 오류

1) npm 명령어를 찾을 수 없다는 오류

npm 명령어를 찾을 수 없다는 오류가 나온다면 Node.js가 설치되지 않았거나, 환경 변수 설정이 제대로 되지 않은 경우입니다. 이 경우 Node.js를 다시 설치한 뒤 터미널을 새로 열어 확인해보는 것이 좋습니다.

2) npm install을 하지 않고 실행한 경우

프로젝트를 만든 직후 바로 npm run dev를 실행하면 필요한 패키지가 없어서 오류가 날 수 있습니다. 반드시 프로젝트 폴더 안에서 먼저 아래 명령어를 실행해야 합니다.


npm install

3) 프로젝트 폴더 밖에서 명령어를 실행한 경우

npm run dev는 React 프로젝트 폴더 안에서 실행해야 합니다. 만약 오류가 발생한다면 현재 터미널 위치가 프로젝트 폴더 안인지 확인해야 합니다.


cd my-react-app
npm run dev

10. 전체 명령어 정리

지금까지 진행한 명령어를 한 번에 정리하면 다음과 같습니다.


npm create vite@latest my-react-app -- --template react

cd my-react-app

npm install

npm run dev

이 네 단계만 기억하면 기본 React 프로젝트를 만들고 실행할 수 있습니다.

11. 정리

이번 글에서는 Vite를 이용해 React 개발환경을 만드는 방법을 알아보았습니다. 처음에는 터미널 명령어가 낯설 수 있지만, 실제로는 프로젝트 생성, 폴더 이동, 패키지 설치, 개발 서버 실행의 순서만 이해하면 됩니다.

React 개발환경 만들기 순서
1. Node.js 설치 확인
2. Vite로 React 프로젝트 생성
3. 프로젝트 폴더로 이동
4. npm install 실행
5. npm run dev로 개발 서버 실행

이제 React 코드를 직접 작성하고 브라우저에서 확인할 수 있는 준비가 끝났습니다. 다음 글에서는 React에서 HTML처럼 보이는 문법인 JSX에 대해 정리해보겠습니다.

GWDEVELBlog 정리
React를 공부할 때 개발환경 설정은 첫 번째 관문입니다. Vite를 사용하면 복잡한 설정 없이 빠르게 React 프로젝트를 만들 수 있고, 앞으로 컴포넌트, JSX, props, state 같은 핵심 개념을 실습하기 좋은 환경을 갖출 수 있습니다.

'Tech Stack > React' 카테고리의 다른 글

[React] 01. React란? 왜 웹 개발에서 많이 사용할까?  (0) 2026.05.16
Tech Stack/React 카테고리의 다른 글 더보기

티스토리툴바