개발 환경 설정

개념을 읽을 때는 이해한 것 같은데, 막상 시작하려니 손이 멈추는 순간이 자주 옵니다. React 입문에서 가장 많이 막히는 곳도 개발 환경 설정입니다. 설치 순서가 꼬이거나 버전이 어긋나면 첫 화면을 띄우기도 전에 오류 메시지와 씨름하게 되기 때문입니다.

그래서 이 글은 설치 목록을 나열하는 데서 그치지 않고, 각 도구가 왜 필요한지와 어디서 실수하기 쉬운지를 함께 설명합니다. 명령을 복사했는데 실행되지 않는 상황을 줄이도록 단계마다 확인할 신호도 적어 두었으니, 순서대로 따라가면 최소한의 설정으로 React 프로젝트를 안정적으로 실행할 수 있습니다.

node -v

npm -v

code --help
또는 앱 메뉴에서 폴더 열기

위 그림은 준비할 도구마다 설치가 끝났다는 화면 대신 확인할 실제 신호를 보여 줍니다. Node.js LTS는 브라우저 밖에서 Vite와 npm 스크립트를 실행하는 도구로, node -v가 버전을 출력하고 그 버전이 지원 중인 LTS이면서 현재 Vite의 요구사항을 만족하는지 확인합니다. npm은 템플릿과 프로젝트의 의존성을 설치하고 package.json의 스크립트를 실행하며, 새 터미널에서 npm -v가 버전을 출력하는지 봅니다.

VS Code는 프로젝트 루트를 하나의 작업 공간으로 열어 소스와 통합 터미널을 함께 쓰는 도구입니다. 터미널에서 code --help가 사용법을 출력하면 code 명령을 쓸 수 있다는 신호이고, 프로젝트 폴더는 code .이나 앱 메뉴의 폴더 열기로 엽니다. 브라우저에서는 터미널에 실제로 출력된 Local 주소를 열어 React 화면을 확인하고, 문제가 있으면 Console과 Network에서 첫 오류를 찾습니다. 그림의 설명처럼 node -v와 npm -v가 버전을 출력했다는 것은 PATH에서 실행 파일을 찾았다는 뜻일 뿐이므로, 지원 중인 LTS인지와 설치 경고를 확인한 뒤 프로젝트를 실행합니다.

정리하면 준비할 도구는 세 가지입니다. 자바스크립트 런타임이자 패키지 관리 도구인 Node.js와 npm, 코드를 작성하고 편집하는 코드 편집기(이 글은 Visual Studio Code를 씁니다), 만든 웹 애플리케이션을 확인하는 웹 브라우저(이 글은 Google Chrome을 씁니다)입니다. 이미 준비된 PC나 클라우드 작업 공간이라면 먼저 아래의 버전 확인부터 해 보고, Node.js와 npm이 있고 조건을 만족하면 설치 단계를 건너뜁니다. 브라우저와 편집기는 웹 기반 도구를 써도 되며, 편집기의 확장 프로그램은 첫 화면을 띄우는 데 꼭 필요하지는 않습니다.

Node.js와 npm 설치

React는 웹 브라우저에서 실행되는 자바스크립트 라이브러리이지만, React로 개발하는 과정에는 Node.js 환경이 필요합니다. Node.js는 자바스크립트 코드를 브라우저 밖에서 실행할 수 있게 해 주는 런타임이고, npm(Node Package Manager)은 Node.js 생태계의 패키지(라이브러리)를 관리하는 도구입니다. React 프로젝트를 만들고 필요한 라이브러리를 설치할 때 npm을 씁니다.

설치하려면 먼저 Node.js 공식 웹사이트에 접속해 운영체제에 맞는 현재 LTS(Long Term Support) 설치 방법을 고릅니다. 이 교재는 Node.js의 특정 버전 번호를 고정하지 않습니다. Node.js의 지원 상태와 Vite의 최소 요구 버전은 바뀔 수 있으므로, 설치하는 시점의 Node.js 릴리스 표와 Vite 시작 안내를 함께 보고 두 조건을 모두 만족하는 지원 중인 LTS를 쓰세요. 이 글을 쓴 2026년 11월 기준으로 Vite 8은 Node.js 20.19 이상 또는 22.12 이상을 요구하며, 선택한 템플릿이 더 높은 버전을 요구할 수 있다고 안내합니다. 6장에서 쓰는 React Router 8.5는 Node.js 22.22 이상을 요구하므로, 22 계열을 쓴다면 이 조건도 확인합니다. npm이 업그레이드 경고를 보여 주면 그 경고와 최신 Vite 안내를 따릅니다.

내려받은 설치 파일을 실행하면 설치 마법사가 나타나는데, 특별한 설정 없이 Next(다음)를 계속 눌러 기본 설정으로 설치하고 마지막에 Finish(마침)를 누릅니다. 이 설명은 Windows 설치 파일을 기준으로 하며, macOS나 Linux, 관리형 작업 공간에서는 공식 다운로드 페이지에 있는 해당 운영체제의 설치 방법을 따릅니다. 중간에 Chocolatey나 Tools for Native Modules 같은 추가 설치 옵션이 나타날 수 있는데, 보통은 선택하지 않고 진행해도 됩니다.

설치를 마쳤으면 Node.js와 npm이 제대로 설치되었는지 확인하기 위해 터미널을 엽니다. Windows에서는 Windows 키 + R을 누르고 cmd를 입력한 뒤 Enter를 누르거나, 시작 메뉴에서 명령 프롬프트를 검색해 실행합니다. macOS에서는 Command + Space로 Spotlight를 열고 터미널을 검색해 실행합니다. 터미널에 다음 명령을 입력하고 Enter를 누릅니다.

node -v
npm -v

제대로 설치되었다면 node -v는 v로 시작하는 버전을, npm -v는 숫자만으로 된 버전을 점으로 구분해 출력합니다. 정확한 숫자는 설치한 시점과 배포판에 따라 다르므로 예시의 숫자와 똑같은지 비교하지 말고, 새 터미널의 PATH에서 두 실행 파일을 찾는지와 그 버전이 현재 Vite의 요구사항을 만족하는지를 확인하세요.

코드 에디터 설치 (Visual Studio Code)

코드를 작성하고 편집하는 도구로는 Visual Studio Code(VS Code)를 권합니다. VS Code는 Microsoft가 오픈 소스 저장소(Code - OSS)를 바탕으로 만들어 무료로 배포하는 코드 편집기로, 가볍고 빠르며 여러 확장 기능(extension)으로 개발 생산성을 높일 수 있습니다.

Visual Studio Code 공식 웹사이트에 접속해 화면 가운데의 다운로드 버튼으로 운영체제에 맞는 설치 파일을 내려받아 실행합니다. Windows에서는 설치할 때 PATH에 추가, Code로 열기 동작 추가 같은 옵션을 모두 선택해 두면 프로젝트 폴더를 VS Code로 편하게 열 수 있습니다. macOS에서는 .dmg 파일을 열어 Visual Studio Code 아이콘을 Applications 폴더로 끌어다 놓습니다.

확장 프로그램은 선택 사항이지만 설치해 두면 편리합니다. VS Code를 실행한 뒤 왼쪽 사이드바의 확장(Extensions) 아이콘을 누르거나 Ctrl+Shift+X(macOS는 Cmd+Shift+X)를 눌러 확장 마켓플레이스를 열고, 검색창에 이름을 입력해 Install(설치)을 누르면 됩니다. React 개발에 유용한 확장은 다음과 같습니다.

• Oxc: 이 글의 명령으로 만든 Vite React 템플릿은 ESLint 대신 Oxlint를 쓰므로(.oxlintrc.json, npm run lint), Oxc 확장을 설치하면 React 훅의 규칙과 잠재적인 코드 오류를 편집하는 단계에서 알려 줍니다. ESLint로 설정한 프로젝트라면 같은 일을 ESLint 확장이 합니다.
• Prettier - Code formatter: 코드를 일관된 스타일로 자동 정리해, 협업할 때 코드 스타일을 맞추고 읽기 쉽게 해 줍니다.
• Auto Rename Tag: HTML이나 JSX의 시작 태그를 바꾸면 닫는 태그도 자동으로 바꿔 줍니다.
• Material Icon Theme나 vscode-icons: 파일과 폴더의 아이콘을 종류별로 구분하기 쉽게 바꿔 줍니다.

첫 React 프로젝트 생성하기

Node.js와 VS Code가 준비되었으니 첫 React 프로젝트를 만들어 봅니다. 이 교재는 지금 가장 널리 쓰이는 시작 방법 가운데 하나인 Vite를 씁니다. Vite는 빠른 개발 서버와 간결한 설정을 제공해, 입문 단계에서도 복잡한 번들 설정 없이 바로 개발을 시작하게 해 줍니다. 예전에는 다른 스타터 도구를 많이 썼지만, 지금은 초기 속도와 설정의 단순함 덕분에 Vite가 학습과 실무 모두에서 유리한 경우가 많습니다. 특히 입문 단계에서는 빌드 도구를 깊이 이해하는 것보다, 코드를 고치면 화면이 바로 바뀌는 짧은 반복을 만드는 편이 학습에 훨씬 도움이 됩니다. 다만 도구가 단순해도 Node.js의 버전과 패키지 설치 상태가 어긋나면 실행에 실패하므로, 단계마다 확인 명령을 함께 점검하는 습관을 들이세요.

React 공식 문서는 새로 만드는 프로덕션 앱이라면 라우팅과 데이터 로딩 같은 기능을 통합한 프레임워크부터 검토하라고 안내합니다(React 문서의 새 React 앱 만들기). 이 글의 Vite 템플릿은 React의 기본 원리와 클라이언트 앱의 구조를 직접 익히기 위한 출발점이며, 완성된 프로덕션 아키텍처를 대신하지는 않습니다.

먼저 터미널을 열고 프로젝트를 만들 폴더로 이동합니다. 예를 들어 C:\Users\YourName\Documents나 ~/Documents에 프로젝트를 만들려면 다음과 같이 입력합니다.

# Windows 예시
cd C:\Users\YourName\Documents

# macOS/Linux 예시
cd ~/Documents

경로의 YourName은 자신의 계정 이름으로 바꾸고, 공백이 있는 경로는 따옴표로 묶으세요. 아직 작업할 폴더가 없다면 mkdir my-react-projects처럼 폴더를 만든 뒤 그 폴더로 이동해도 됩니다. 만들려는 프로젝트 이름의 폴더가 이미 있다면 기존 폴더를 덮어쓰지 말고, 비어 있는 작업 폴더나 다른 이름을 고르세요.

이제 다음 명령으로 my-first-react-app이라는 새 React 프로젝트를 만듭니다. 프로젝트 이름은 자유롭게 정할 수 있습니다.

npm create vite@latest my-first-react-app -- --template react --no-interactive

npm create는 템플릿을 바탕으로 프로젝트를 초기화하는 명령이고, -- 뒤의 옵션은 create-vite에 그대로 전달됩니다. --template react는 React 템플릿을 고르고, --no-interactive는 린터로 Oxlint와 ESLint 가운데 무엇을 쓸지 묻는 질문과 바로 설치하고 실행할지 묻는 질문을 건너뛰어 이 글의 단계를 누구나 같은 순서로 따라 하게 해 줍니다. 이때 린터는 Oxlint로 정해지고 설치는 하지 않으므로, 프로젝트를 만든 직후에는 의존성 설치(npm install)를 직접 한 번 해야 합니다. create-vite 패키지를 내려받아도 되는지 npm이 따로 묻는 확인 질문이 나타날 수도 있습니다. 내려받기가 거부되거나 실패했다면 그 단계의 오류를 먼저 확인하고, 프로젝트가 만들어졌다고 간주하지 않습니다.

프로젝트가 만들어지면 새로 생긴 프로젝트 폴더로 이동합니다.

cd my-first-react-app

이동한 폴더에는 package.json과 src 같은 템플릿 파일만 있고, React 패키지를 담을 node_modules는 아직 없습니다. 마지막으로 의존성을 설치하고 개발 서버를 시작해 React 애플리케이션을 실행합니다. npm install은 package.json에 적힌 패키지를 내려받아 node_modules를 만들고, npm run dev는 같은 파일의 dev 스크립트로 Vite 개발 서버를 띄웁니다. 개발 서버는 터미널을 차지한 채 계속 실행되므로, 끝낼 때는 그 터미널에서 Ctrl + C를 누릅니다.

npm install
npm run dev

npm run dev를 실행하면 터미널에 Local: http://localhost:5173/처럼 개발 서버의 Local 주소가 나타납니다. 기본 포트는 5173이지만 이미 쓰고 있다면 Vite가 다음으로 비어 있는 포트를 고를 수 있으므로, 주소를 짐작하지 말고 터미널에 실제로 출력된 주소를 브라우저에서 여세요. 브라우저에 Vite와 React의 기본 화면이 나타나고 파일을 저장할 때마다 화면이 빠르게 바뀐다면, 첫 React 프로젝트를 실행하는 흐름이 제대로 연결된 것입니다.

위 그림은 방금 진행한 버전 확인, 프로젝트 생성, 개발 서버 실행을 코드 수정과 이어지는 하나의 반복으로 묶어 보여 줍니다. 버전을 확인하고, npm create vite로 React 템플릿을 만들고, 프로젝트 루트로 이동해 npm install로 의존성을 설치한 뒤, npm run dev로 개발 서버를 띄워 실제 Local 주소를 확인합니다. 브라우저에서 화면과 Console, Network의 첫 오류를 살핀 다음 같은 프로젝트의 App.jsx를 고쳐 저장하면, Fast Refresh가 바뀐 모듈을 반영하고 다시 브라우저에서 결과를 확인합니다.

명령을 외우기보다, 어느 단계에서 오류가 났는지 나눠서 확인하는 데 이 그림을 쓰세요. 그림의 설명처럼 중간에 멈췄다고 모든 도구를 다시 설치할 필요는 없습니다. 생성과 설치, 서버 단계의 문제는 터미널의 첫 오류에서, 화면 단계의 문제는 Console과 Network에서 범위를 좁힙니다. 또 저장할 때마다 main.jsx가 다시 실행되는 것은 아니며, Fast Refresh가 지원하지 않는 변경이라면 전체 새로고침이 일어날 수 있습니다. 반복은 코드 수정과 화면 확인 사이에서 일어나고, 처음의 생성과 설치 단계로 되돌아가지는 않습니다.

VS Code로 프로젝트 열기

이제 실행 중인 React 프로젝트를 VS Code에서 열어 코드를 확인해 봅니다. VS Code를 실행한 뒤 메뉴에서 File (파일) > Open Folder (폴더 열기...)를 선택해 my-first-react-app 폴더를 열 수 있습니다. 터미널에서 프로젝트 폴더로 이동한 상태라면 다음 명령으로 VS Code가 그 폴더를 열며 실행되므로 더 편리합니다.

code .

여기서 .은 현재 디렉터리를 뜻합니다. macOS에서는 먼저 VS Code의 명령 팔레트에서 Shell Command: Install 'code' command in PATH를 실행해야 하고, Windows나 Linux에서도 code를 찾지 못한다면 VS Code 설치의 PATH 설정을 확인합니다.

VS Code의 탐색기(Explorer)에서 my-first-react-app 폴더의 구조를 볼 수 있고, src 폴더의 App.jsx 파일을 열면 React 컴포넌트 코드가 보입니다. 이 코드를 고쳐 저장하면 Vite가 바뀐 모듈을 감지합니다. create-vite의 React 템플릿에는 React Fast Refresh가 미리 구성되어 있어서 지원되는 변경은 페이지 전체를 다시 불러오지 않고 빠르게 반영되며, 변경의 종류에 따라서는 전체 새로고침이 일어나기도 합니다. 개발 환경을 갖출 때는 설치가 끝났다는 사실보다, 저장한 코드가 개발 서버와 브라우저에 바로 반영되는 반복을 확인하는 것이 중요합니다.

이때 지금 어느 폴더에 있고 어떤 터미널이 실행 중인지도 구분해야 합니다. npm run dev는 서버가 도는 동안 그 터미널을 계속 차지하므로, 다른 명령은 그 터미널에 이어 입력하지 말고 새 터미널을 열거나 편집기의 폴더 열기를 씁니다. 새 터미널에서도 프로젝트 루트의 package.json이 보이는지 먼저 확인하세요. 서버 터미널에서 Ctrl+C로 서버를 끝내면 편집한 파일은 그대로 남지만, 그 주소로 화면을 제공하는 일은 멈춥니다.

정리

• React 개발에는 Vite와 npm 스크립트를 실행할 Node.js와 npm, 코드 편집기, 브라우저가 필요합니다.
• Node.js는 지원 중인 LTS이면서 Vite의 요구사항(20.19 이상 또는 22.12 이상)을 만족하는 버전을 쓰고, 6장의 React Router 8.5는 22.22 이상을 요구합니다.
• node -v와 npm -v의 출력은 PATH에서 실행 파일을 찾았다는 신호일 뿐이므로, 버전 조건과 설치 경고도 함께 확인합니다.
• npm create vite@latest 이름 -- --template react --no-interactive로 프로젝트를 만들고, 프로젝트 폴더에서 npm install과 npm run dev를 실행합니다.
• 개발 서버의 주소는 짐작하지 말고 터미널에 실제로 출력된 Local 주소를 엽니다.
• 문제가 생기면 생성·설치·서버 단계는 터미널의 첫 오류로, 화면 단계는 Console과 Network로 범위를 좁힙니다.

연습 문제

1. package.json을 찾지 못하는 오류

node -v와 npm -v는 버전을 출력하는데, npm run dev를 실행하니 package.json을 찾지 못한다는 오류가 났습니다. Vite 프로젝트의 생성과 설치는 성공했고, 지금 연 새 터미널은 프로젝트의 상위 폴더에 있습니다. Node.js를 다시 설치해야 할까요?

2. 직접 입력한 5173 주소

다른 터미널에서 개발 서버가 실행 중인데, 브라우저 주소창에 http://localhost:5173을 직접 입력했더니 화면이 열리지 않습니다. 무엇부터 확인해야 할까요?

다음 글 첫 번째 React 앱 만들기에서는 방금 만든 프로젝트의 src/App.jsx를 직접 고쳐 첫 화면을 바꿔 봅니다.