개발 환경 설정 (Node.js + Vite)

1장에서 리액트가 무엇이고 이 책이 어디로 향하는지 봤습니다. 이번 챕터에서는 손에 도구를 깔겠습니다. 본문의 모든 예제가 이 챕터에서 만든 환경 위에서 돌아갑니다.

본 챕터에서 할 일은 세 가지입니다.

1. Node.js 22 LTS 설치
2. pnpm 활성화
3. Vite로 새 리액트 프로젝트 생성 + dev server 실행

도구를 정확히 골라 두는 게 중요합니다. 이 책은 처음부터 끝까지 같은 도구 세트를 가정하고 흐릅니다. 4부의 Next.js, 5부의 테스팅/배포, 6부의 풀스택 capstone까지 모두 이 환경을 그대로 확장하는 모양으로 이어집니다.

Node.js가 무엇이고 왜 필요한가 #

리액트는 자바스크립트 라이브러리입니다. 그런데 우리가 작성하는 리액트 코드(JSX, 모듈 import 등)는 브라우저가 곧바로 이해하지 못하는 문법을 포함합니다. 실행 가능한 자바스크립트로 변환(transpile + bundle)하는 빌드 과정이 필요한데, 그 빌드 도구가 동작하려면 자바스크립트 런타임이 필요합니다. 그것이 Node.js입니다.

Node.js는 원래 서버 개발을 위해 만들어졌지만, 오늘날 프론트엔드 개발자도 Node.js 위에서 돌아가는 도구들(번들러, 컴파일러, 패키지 매니저, 테스트 러너)을 매일 씁니다. 리액트로 개발하려면 Node.js가 필수입니다.

버전 선택 — LTS #

추천 버전은 Node.js 22 LTS입니다. LTS는 Long Term Support의 약자로, 일정 기간 안정성과 보안 패치가 보장되는 버전입니다. nodejs.org에 가면 LTS와 Current 두 버전이 보이는데, 처음 시작하거나 실무 프로젝트라면 LTS를 받습니다.

이 책의 코드는 Node.js 22 LTS를 기준으로 동작을 검증했습니다. 그 이상 버전이면 거의 동일하게 동작합니다.

Node.js 설치 #

운영체제별로 절차가 조금 다릅니다.

macOS #

가장 깔끔한 방법은 Homebrew를 통한 설치입니다.

brew install node@22

Homebrew를 쓰지 않는다면 nodejs.org에서 .pkg 설치 파일을 받아 더블클릭으로 설치합니다.

Linux #

대부분의 배포판에서는 패키지 매니저로 설치할 수 있지만 버전이 약간 옛것인 경우가 있어, NodeSource 저장소를 추가하거나 nvm으로 받는 쪽이 안전합니다.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 새 터미널을 연 뒤
nvm install 22
nvm use 22

nvm은 여러 Node.js 버전을 한 머신에서 골라 쓸 수 있게 해 줍니다. 프로젝트마다 Node.js 버전이 다른 환경이라면 추천합니다.

Windows #

두 가지 길이 있습니다.

선택 1. WSL2 + Linux 절차 (권장)

요즘 Windows에서 프론트엔드 개발을 한다면 WSL2 (Windows Subsystem for Linux 2) 안에서 작업하는 쪽이 거의 표준입니다. Linux 셸 / 파일 시스템에서 위 nvm 절차를 그대로 따르면 됩니다.

WSL이 처음이라면 PowerShell을 관리자로 열고:

wsl --install

그 뒤 Ubuntu 터미널을 열어 nvm 절차를 진행합니다. VS Code에는 Remote - WSL 확장을 설치하면 Windows에 띄운 에디터로 WSL 안 파일을 직접 편집할 수 있습니다.

선택 2. Windows 네이티브 설치

WSL이 부담스럽다면 nodejs.org에서 .msi 설치 파일을 받아 설치하는 길도 있습니다. 다만 일부 도구(특히 node_modules 내부의 OS-specific 바이너리)가 Windows 네이티브 경로에서 느리거나 어색한 경우가 있습니다. WSL 쪽이 결국은 마찰이 적습니다.

설치 확인 #

설치가 끝나면 터미널을 새로 열고 버전을 확인합니다.

node -v
# v22.x.x

npm -v
# 10.x.x

npm은 Node.js와 함께 자동으로 설치되는 기본 패키지 매니저입니다. 다만 이 책은 다음 절에서 다룰 pnpm을 1차로 씁니다.

pnpm 활성화 #

이 책은 패키지 매니저로 pnpm을 사용합니다. npm / yarn도 거의 같은 명령어 체계이고 위에서 자동 설치된 npm으로도 모든 예제가 동작합니다만, pnpm을 권장하는 이유는 다음과 같습니다.

• 빠른 설치 속도 — 글로벌 store에서 hard link로 의존성을 공유해 디스크 공간도 절약
• monorepo 친화 — 이 책의 6부 capstone에서 workspaces 기능을 잠깐 활용
• strict한 의존성 해석 — package.json에 선언하지 않은 패키지를 실수로 임포트하는 사고를 줄임

pnpm은 Node.js 16.13 이상에 내장된 Corepack으로 간단히 활성화합니다.

corepack enable
corepack prepare pnpm@latest --activate
pnpm -v
# 10.x.x

이후 이 책의 모든 명령은 pnpm을 기준으로 씁니다. npm/yarn 사용자도 다음 매핑만 알면 거의 그대로 따라올 수 있습니다.

Vite로 새 프로젝트 만들기 #

이제 첫 리액트 프로젝트를 만들겠습니다. 빌드 도구로는 Vite (“비트"로 발음, 프랑스어로 “빠르다”)를 씁니다.

Vite는 리액트를 포함한 여러 프론트엔드 프레임워크용 빌드 도구입니다. 새 프로젝트의 초기 설정을 자동으로 만들어 주고, 개발 중에는 매우 빠른 dev server를 띄웁니다. 예전 표준이었던 create-react-app은 공식적으로 deprecated되었고, 지금은 Vite가 사실상의 표준입니다.

원하는 위치 (예: ~/projects)로 이동한 뒤 터미널에서:

pnpm create vite@latest

명령어를 실행하면 몇 가지 질문을 받습니다.

1. Project name — 프로젝트 폴더 이름. 원하는 이름을 입력합니다 (예: my-first-react)
2. Select a framework — React를 선택합니다
3. Select a variant — JavaScript를 선택합니다. TypeScript는 이 책의 3부에서 본격적으로 다루겠습니다

선택이 끝나면 Vite가 프로젝트 폴더를 만들어 줍니다. 마지막에 다음과 비슷한 안내가 보입니다.

Done. Now run:

  cd my-first-react
  pnpm install
  pnpm dev

안내대로 따라갑니다.

cd my-first-react
pnpm install

pnpm install은 package.json에 선언된 의존성(리액트 본체, Vite, 기타 도구들)을 글로벌 store에 다운로드하고 node_modules 폴더에 hard link로 연결합니다. 처음에는 약간 시간이 걸리지만, 두 번째 프로젝트부터는 store에 이미 받아 둔 패키지를 재사용하므로 훨씬 빠릅니다.

Dev server 실행 #

이제 dev server를 띄워 보겠습니다.

pnpm dev

다음과 비슷한 출력이 보이면 성공입니다.

  VITE v6.x.x  ready in 250 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

브라우저를 열고 http://localhost:5173에 접속합니다. Vite + React로고가 회전하는 기본 화면이 보이면 모든 것이 정상입니다.

프로젝트 구조 살펴보기 #

열어 둔 프로젝트 폴더의 구조는 다음과 같습니다.

my-first-react/
├── node_modules/        ← 설치된 라이브러리 (직접 건드릴 일 없음)
├── public/              ← 정적 파일 (이미지, favicon 등)
├── src/                 ← 우리가 작성할 코드가 들어갈 곳
│   ├── App.jsx          ← 첫 번째 컴포넌트
│   ├── main.jsx         ← 앱의 진입점
│   ├── App.css
│   └── index.css
├── index.html           ← 앱이 주입될 HTML
├── package.json         ← 프로젝트 정보와 의존성 목록
└── vite.config.js       ← Vite 설정

지금 단계에서 가장 중요한 파일은 **src/App.jsx**입니다. 화면에 보여줄 내용을 작성하는 곳입니다.

첫 수정 — Hot Module Replacement 체험 #

VS Code (권장 에디터)로 프로젝트 폴더를 엽니다. src/App.jsx를 열면 다음과 같은 코드가 보입니다.

import { useState } from 'react'
import reactLogo from './assets/react.svg'
import viteLogo from '/vite.svg'
import './App.css'

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

  return (
    <>
      <div>
        {/* ... */}
      </div>
      <h1>Vite + React</h1>
      {/* ... */}
    </>
  )
}

export default App

<h1>Vite + React</h1> 부분을 다음과 같이 바꿉니다.

<h1>안녕하세요, 리액트!</h1>

저장하면 dev server를 끄거나 새로고침을 하지 않아도 브라우저 화면이 즉시 갱신됩니다. 이 기능이 **HMR (Hot Module Replacement)**입니다. 변경된 모듈만 실시간으로 교체해 화면에 반영해 줍니다. 개발 속도를 크게 끌어올려 주니 앞으로 자주 보게 됩니다.

연습문제 #

1. 본 챕터의 절차대로 my-first-react 프로젝트를 만들고 dev server를 띄운 뒤, src/App.jsx의 <h1> 텍스트를 본인의 이름이 들어간 인사로 바꿔 보세요. 저장과 동시에 브라우저가 갱신되는 것을 확인하면 됩니다.
2. src/App.jsx 안에서 <h1> 한 줄 아래에 새로운 <p>오늘은 리액트 첫날입니다.</p> 한 줄을 추가해 보세요. 저장 후 화면에 두 줄이 모두 보이는지 확인합니다.
3. pnpm으로 dayjs 라이브러리를 추가(pnpm add dayjs)한 뒤 App.jsx 안에서 import dayjs from 'dayjs'로 가져와 <p>오늘은 {dayjs().format('YYYY-MM-DD')}입니다.</p> 한 줄로 오늘 날짜를 화면에 표시해 보세요. package.json의 dependencies에 dayjs가 추가되어 있는 것도 함께 확인합니다.

한 줄 요약: 이 책은 Node.js 22 LTS + pnpm + Vite를 표준으로 깐다. pnpm create vite@latest로 프로젝트를 만들고, pnpm install로 의존성을 받고, pnpm dev로 dev server를 띄우는 세 단계가 일상의 전부다. HMR 덕분에 코드를 저장하면 브라우저가 즉시 갱신된다.

다음 챕터 #

다음 3장 JSX의 본질에서는 본 챕터에서 슬쩍 본 <h1>안녕하세요, 리액트!</h1> 같은 코드가 정확히 무엇이고 어떻게 자바스크립트로 변환되는지를 살펴보겠습니다. 표현식 / 속성 / 자식 규칙까지 한 번에 다루겠습니다.