[React] Installation

공식 문서: React - Creating a React App, React - Build a React app from Scratch, Vite - Getting Started

React 설치 방식

React project를 시작하는 방법은 크게 두 가지로 나눌 수 있다.

React 공식 문서에서는 production app을 만들 때 framework 사용을 권장한다. 하지만 React의 기본 구조를 학습하거나, client-side app을 가볍게 시작하려면 Vite로 React project를 만드는 방식이 간단하다.

이 글에서는 Vite를 이용해 React project를 설치하고 실행하는 방법을 정리한다.

사전 준비

먼저 Node.js와 npm이 설치되어 있어야 한다.

node --version
npm --version

Vite 공식 문서 기준으로 Vite는 Node.js 20.19+ 또는 22.12+ 이상을 요구한다. 버전이 낮다면 Node.js를 먼저 업데이트해야 한다.

Vite로 React project 생성

가장 단순한 방법은 npm create vite@latest를 사용하는 것이다.

npm create vite@latest

명령어를 실행하면 project 이름과 framework를 선택하는 prompt가 나온다.

Project name: my-react-app
Select a framework: React
Select a variant: JavaScript 또는 TypeScript

React + TypeScript로 바로 만들고 싶다면 template을 명시할 수 있다.

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

JavaScript template을 사용하려면 다음처럼 입력한다.

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

의존성 설치

project directory로 이동한다.

cd my-react-app

의존성을 설치한다.

npm install

이 단계에서 package.json에 적힌 React, Vite, TypeScript 관련 package가 설치된다.

개발 서버 실행

개발 서버를 실행한다.

npm run dev

Vite 기본 개발 서버는 보통 다음 주소로 열린다.

http://localhost:5173

terminal에 표시된 URL을 browser에서 열면 React app을 확인할 수 있다.

생성된 project 구조

Vite React project의 기본 구조는 대략 다음과 같다.

my-react-app/
  index.html
  package.json
  vite.config.ts
  src/
    App.tsx
    main.tsx
    assets/

주요 파일은 다음과 같다.

Vite에서는 index.html이 project root에 있는 것이 자연스럽다. src/main.tsx에서 React component를 실제 DOM에 연결한다.

main.tsx

React entry file은 보통 다음 형태이다.

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>,
)

핵심은 createRoot()이다. index.html의 root element를 찾아서 React app을 mount한다.

<div id="root"></div>

App component 수정

src/App.tsx를 간단히 바꿔보자.

function App() {
  return (
    <main>
      <h1>Hello React</h1>
      <p>React app is running.</p>
    </main>
  )
}

export default App

파일을 저장하면 Vite의 HMR이 동작해서 browser가 빠르게 갱신된다.

npm script

package.json에는 보통 다음 script가 들어 있다.

{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  }
}

자주 쓰는 명령어는 다음과 같다.

production build

배포용 파일을 만들려면 다음 명령어를 사용한다.

npm run build

성공하면 dist directory가 생성된다.

dist/
  index.html
  assets/

이 dist directory를 정적 hosting 서비스에 배포하면 된다.

local에서 build 결과를 확인하려면 다음 명령어를 사용한다.

npm run preview

TypeScript를 선택할까?

처음 React를 학습하는 단계라면 JavaScript template도 충분하다. 하지만 실제 project에서는 TypeScript template을 선택하는 경우가 많다.

TypeScript를 사용하면 props, state, API response type을 명확히 관리할 수 있다.

자주 생기는 문제

npm create가 실패하는 경우

Node.js 버전이 낮을 수 있다.

node --version

Vite 요구 버전을 만족하지 않으면 Node.js를 업데이트한다.

port가 이미 사용 중인 경우

기본 port 5173이 이미 사용 중이면 Vite가 다른 port를 제안한다. 직접 port를 지정할 수도 있다.

npm run dev -- --port 3000

dependency 설치가 꼬인 경우

node_modules와 lock file을 지우고 다시 설치할 수 있다.

rm -rf node_modules package-lock.json
npm install

운영 중인 project에서는 lock file 삭제가 dependency version을 바꿀 수 있으므로 주의해야 한다.

정리

Vite로 React를 설치하는 기본 흐름은 다음과 같다.

npm create vite@latest my-react-app -- --template react-ts
cd my-react-app
npm install
npm run dev

핵심은 다음과 같다.

1. Node.js와 npm을 먼저 준비한다.
2. npm create vite@latest로 project를 생성한다.
3. React template은 react 또는 react-ts를 선택한다.
4. npm install로 dependency를 설치한다.
5. npm run dev로 개발 서버를 실행한다.
6. 배포 전에는 npm run build로 production build를 만든다.

학습용 또는 client-side app은 Vite React template으로 빠르게 시작할 수 있다. SSR, file-based routing, server function 같은 기능이 필요하면 Next.js나 React Router framework 같은 선택지를 검토하는 것이 좋다.