리액트 설치: Vite로 React 앱 만들기

React를 설치하려면 Vite로 새 프로젝트를 만드세요. npm create vite@latest my-app -- --template react를 실행한 다음 cd my-app, npm install, npm run dev를 실행합니다. 먼저 Node.js가 설치되어 있어야 합니다. Vite는 React, JSX 컴파일, 그리고 저장할 때마다 페이지를 다시 불러오는 개발 서버를 설정해 줍니다.

배우기 시작하는 데는 이런 것이 전혀 필요 없습니다. 아래 에디터는 이 페이지 안에서 React를 실행합니다. Vite가 만들어 주는 App.jsx 파일을 단순하게 줄인 버전입니다.

import { useState } from 'react';

export default function App() {
    const [count, setCount] = useState(0);

    return (
        <div style={{ textAlign: 'center' }}>
            <h1>Get started</h1>
            <p>
                Edit <code>src/App.jsx</code> and save to test <code>HMR</code>
            </p>
            <button type="button" onClick={() => setCount((count) => count + 1)}>
                Count is {count}
            </button>
        </div>
    );
}

버튼을 클릭한 다음 제목 텍스트를 바꿔 보세요. 입력하는 대로 미리보기가 업데이트됩니다. Vite 개발 서버가 페이지를 새로고침하지 않고 변경 사항을 바꿔 끼우는 것과 같은 방식입니다("HMR", 즉 핫 모듈 교체가 이것을 뜻합니다).

사전 준비: Node.js

React 앱을 빌드하는 도구는 Node.js에서 실행되며, 패키지 관리자인 npm이 함께 설치됩니다. Node.js 웹사이트나 nvm 같은 버전 관리자로 현재 LTS 버전을 설치한 뒤 터미널에서 확인하세요.

node -v
npm -v

두 명령 모두 버전 번호를 출력해야 합니다. node -v가 오래된 버전을 출력하면 업그레이드하세요. Vite 8은 Node.js 20.19 이상(22 버전대에서는 22.12 이상)이 필요하며, 더 오래된 버전에서는 경고를 출력합니다.

Vite로 React 앱 만들기

프로젝트를 보관하는 폴더에서 다음 네 개의 명령을 실행하세요.

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

• npm create vite@latest는 최신 프로젝트 생성기를 내려받습니다. my-app은 폴더 이름이고, --template react는 자바스크립트를 쓰는 일반 React를 선택합니다. 추가로 붙은 --는 템플릿 옵션을 npm을 거쳐 생성기로 전달합니다.
• npm install은 package.json에 나열된 React, React DOM, Vite 등의 의존성을 node_modules로 내려받습니다.
• npm run dev는 개발 서버를 시작하고 로컬 주소를 출력합니다. 보통 http://localhost:5173입니다. 브라우저에서 여세요.

그다음 생성기가 두 가지를 묻습니다. 어떤 린터를 설정할지(Oxlint 또는 ESLint), 그리고 지금 앱을 설치하고 시작할지입니다. 두 번째 질문에 예라고 답하면 npm install과 npm run dev를 대신 실행하므로 마지막 두 명령은 건너뛰어도 됩니다. TypeScript를 쓰려면 대신 --template react-ts를 사용하세요. React와 TypeScript를 참고하세요.

Vite가 만드는 파일

my-app/
├── index.html
├── package.json
├── vite.config.js
├── README.md
├── public/
└── src/
    ├── main.jsx
    ├── App.jsx
    ├── App.css
    ├── index.css
    └── assets/

이 중 가장 중요한 파일은 세 개입니다.

index.html 은 브라우저가 불러오는 페이지입니다. body에는 빈 요소 하나 <div id="root"></div>와 src/main.jsx를 불러오는 script 태그가 있습니다. React는 앱 전체를 그 div 안에 그립니다.

src/main.jsx 는 진입점입니다. React를 페이지에 연결합니다.

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

createRoot는 #root 요소를 받아 그 안의 모든 것을 React가 책임지게 합니다. render(<App />)은 최상위 컴포넌트를 그곳에 그립니다. StrictMode는 몇 가지 추가 검사를 실행하는 개발용 도우미로, 프로덕션 빌드에서는 아무 효과가 없습니다(Strict Mode 참고). 이 파일은 거의 수정할 일이 없습니다.

src/App.jsx 는 첫 번째 컴포넌트이자 직접 수정하는 파일입니다. Vite가 만든 버전은 이미지 세 개(히어로 이미지와 Vite, React 로고)와 App.css를 import하고, export default App으로 끝납니다. 이것은 맨 위에 export default function App()이라고 쓰는 것과 같으며, 이 페이지들의 예제는 그 형태를 사용합니다.

첫 번째 수정

src/App.jsx를 열어 내용을 지우고 직접 만든 컴포넌트로 바꾸세요. 저장하면 브라우저가 업데이트됩니다. 입력해 볼 작은 첫 앱이 있습니다. 먼저 여기서 실행해 보세요.

import { useState } from 'react';

function Greeting({ name }) {
    return <h2>Hello, {name}!</h2>;
}

export default function App() {
    const [name, setName] = useState('React');

    return (
        <div>
            <Greeting name={name} />
            <label>
                Your name:{' '}
                <input value={name} onChange={(e) => setName(e.target.value)} />
            </label>
        </div>
    );
}

입력창에 타이핑하면 제목이 따라 바뀝니다. 그다음 첫 번째 줄 아래에 <Greeting name="Vite" />를 하나 더 추가해 보세요. 컴포넌트는 재사용할 수 있고, 각 복사본은 자기만의 name을 받습니다.

App.jsx가 커지면 컴포넌트를 src/Greeting.jsx 같은 별도 파일로 옮기고, export한 다음 사용하는 곳에서 import하세요. 컴포넌트 페이지에서 방법을 보여 줍니다.

프로덕션 빌드

개발 서버는 코드를 작성할 때 쓰는 것입니다. 배포할 준비가 되면 앱을 빌드하세요.

npm run build
npm run preview

npm run build는 JSX를 컴파일하고, 코드를 번들링하고 압축한 뒤, 정적 파일을 dist/ 폴더에 씁니다. npm run preview는 그 폴더를 로컬에서 서빙하므로 실제 빌드를 확인할 수 있습니다. dist/를 아무 정적 호스팅에나 업로드하세요. 빌드에서는 React도 프로덕션 모드로 바뀌어 더 빠르게 동작하고 개발용 경고를 건너뜁니다.

Create React App은 지원 중단되었습니다

오랫동안 표준적인 시작 방법은 npx create-react-app my-app이었습니다. 2025년 2월 React 팀은 Create React App을 지원 중단했고, 더 이상 유지 보수되지 않습니다. 오래된 튜토리얼 중에는 아직 이것을 쓰는 것이 많아서 react-scripts start와 src/index.js 진입 파일을 보게 될 것입니다. 컴포넌트 자체는 Vite 프로젝트에서도 똑같이 동작합니다.

대신 사용할 것은 다음과 같습니다.

• 클라이언트 사이드 앱, 학습용 프로젝트, 위젯에는 Vite: 위의 설정입니다.
• 라우팅, 서버 렌더링, 데이터 로딩이 내장되어야 한다면 프레임워크. Next.js와 React Router의 프레임워크 모드가 흔히 쓰입니다.

npx create-next-app@latest my-app
npx create-react-router@latest my-app

기존 Create React App 프로젝트를 Vite로 옮기는 주요 단계는 다음과 같습니다. vite와 @vitejs/plugin-react를 설치하고 react-scripts를 제거합니다. React 플러그인을 불러오는 vite.config.js를 추가합니다. index.html을 public/에서 프로젝트 루트로 옮기고, %PUBLIC_URL% 자리 표시자를 지우고, 진입 파일을 위한 <script type="module" src="/src/index.jsx"> 태그를 추가합니다. JSX가 들어 있는 파일의 확장자를 .jsx로 바꿉니다. REACT_APP_ 환경 변수의 이름을 VITE_로 바꾸고 import.meta.env에서 읽습니다. 마지막으로 package.json의 react-scripts 명령을 vite, vite build, vite preview로 바꿉니다.

기존 페이지에 React 추가하기

React가 페이지 전체를 맡을 필요는 없습니다. 서버에서 렌더링하는 쇼핑몰의 장바구니 위젯처럼, 기존 사이트의 요소 하나에만 React를 렌더링할 수 있습니다. JSX를 컴파일하려면 여전히 Vite 같은 번들러가 필요합니다. 두 패키지를 설치하세요.

npm install react react-dom

그다음 React가 제어할 요소에 루트를 만듭니다.

import { createRoot } from 'react-dom/client';
import Cart from './Cart.jsx';

const container = document.getElementById('cart');
createRoot(container).render(<Cart />);

#cart 바깥의 모든 것은 그대로 남습니다. 한 페이지에 요소마다 하나씩 여러 루트를 만들 수 있고, 각 루트는 독립적으로 동작합니다.