개발 환경 설정

개념을 읽을 때는 대충 이해한 것 같은데 막상 시작하려니 손이 멈춘다는 순간이 자주 옵니다.

리액트 입문에서 가장 많이 막히는 지점도 바로 개발 환경 설정입니다.

설치 순서가 꼬이거나 버전이 어긋나면 첫 화면을 띄우기 전부터 오류 메시지와 씨름하게 되기 때문입니다.

그래서 이 절은 단순 설치 목록이 아니라, 왜 이 도구가 필요한지와 어디서 실수하기 쉬운지를 함께 설명합니다.

특히 명령어는 복사했는데 실행이 안 되는 상황을 줄이기 위해 확인 포인트를 단계마다 넣었습니다.

이 절의 체크포인트를 순서대로 적용하면, 최소한의 설정으로 리액트 프로젝트를 안정적으로 실행하는 기준을 확보할 수 있습니다.

node -v

npm -v

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

리액트 프로젝트를 개발하기 위해서는 몇 가지 필수적인 도구가 필요합니다.

크게 다음 세 가지를 준비할 것입니다.

그럼, 하나씩 설치하고 설정해 보겠습니다.

이미 준비된 PC나 클라우드 작업 공간이라면 먼저 아래 버전 확인을 실행하세요. Node·npm이 있고 조건을 만족하면 설치 단계를 반복하지 않습니다. 브라우저와 에디터는 웹 기반 도구를 사용할 수도 있습니다. 확장 프로그램은 첫 화면 실행의 필수 조건이 아닙니다.

Node.js와 npm 설치

리액트는 웹 브라우저에서 실행되는 자바스크립트 라이브러리이지만, 리액트 개발 과정에서는 Node.js 환경이 필요합니다.

Node.js는 자바스크립트 코드를 브라우저 밖에서 실행할 수 있게 해주는 런타임 환경이며, npm(Node Package Manager)은 Node.js 생태계의 패키지(라이브러리)들을 관리해주는 도구입니다.

리액트 프로젝트를 생성하고 필요한 라이브러리들을 설치할 때 npm을 사용하게 됩니다.

Node.js와 npm이 제대로 설치되었는지 확인하기 위해 명령 프롬프트(Windows) 또는 터미널(macOS/Linux)을 엽니다.

• Windows: Windows 키 + R을 누르고 cmd를 입력한 후 Enter를 누르거나, 시작 메뉴에서 명령 프롬프트를 검색하여 실행합니다.
• macOS: Command + Space를 눌러 Spotlight를 연 후 터미널을 검색하여 실행합니다.

터미널(또는 명령 프롬프트)에 다음 명령어를 입력하고 Enter를 누릅니다.

node -v
npm -v

성공적으로 설치되었다면 두 명령 모두 점으로 구분된 버전 번호를 출력합니다. 정확한 숫자는 설치 시점과 배포판에 따라 달라지므로 예시 숫자와 비교하지 말고, 두 실행 파일이 새 터미널의 PATH에서 발견되는지와 현재 Vite 요구사항을 만족하는지를 확인하세요.

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

코드를 작성하고 편집하기 위한 도구로 Visual Studio Code (VS Code)를 강력히 추천합니다.

VS Code는 마이크로소프트에서 개발한 무료 오픈소스 코드 에디터로, 가볍고 빠르며, 수많은 확장 기능(Extension)을 통해 개발 생산성을 극대화할 수 있습니다.

VS Code는 확장 프로그램을 통해 다양한 기능을 추가하고 개발 경험을 개선할 수 있습니다.

리액트 개발에 유용한 몇 가지 확장 프로그램을 추천합니다.

VS Code를 실행한 후, 왼쪽 사이드바의 확장(Extensions) 아이콘(네모난 블록 모양)을 클릭하거나 Ctrl+Shift+X (macOS: Cmd+Shift+X)를 눌러 확장 마켓플레이스를 엽니다.

• ESLint: React 훅 규칙과 잠재적인 코드 오류를 편집 단계에서 확인합니다. 프로젝트의 ESLint 설정과 함께 사용하면 팀 전체가 같은 기준으로 문제를 찾을 수 있습니다.
• Prettier - Code formatter: 코드를 일관된 스타일로 자동으로 포맷팅해줍니다. 협업 시 코드 스타일을 통일하고 가독성을 높이는 데 필수적입니다.
• Auto Rename Tag: HTML/JSX 태그의 시작 태그를 변경하면 자동으로 닫는 태그도 변경해줍니다.
• Material Icon Theme / vscode-icons: 파일 및 폴더 아이콘을 시각적으로 구분하기 쉽게 만들어줍니다.

확장 프로그램 검색창에 이름을 입력하고 Install(설치) 버튼을 클릭하여 설치합니다.

첫 React 프로젝트 생성하기

이제 Node.js와 VS Code가 모두 준비되었으니, 드디어 첫 번째 리액트 프로젝트를 생성해 볼 차례입니다.

현재 실무/커뮤니티에서 가장 널리 쓰이는 시작 방식 중 하나인 Vite를 사용하겠습니다.

Vite는 빠른 개발 서버와 간결한 설정을 제공해, 입문 단계에서도 복잡한 번들 설정 없이 바로 개발을 시작할 수 있도록 돕습니다.

과거에는 다른 스타터 도구를 많이 사용했지만, 현재는 초기 속도와 설정 단순성 측면에서 Vite가 학습과 실무 모두에서 유리한 선택이 되는 경우가 많습니다.

특히 빠르게 띄우고 빠르게 수정 반영하기가 중요한 입문 단계에서는, 빌드 체인 이해보다 화면-코드 피드백 루프를 짧게 가져가는 것이 학습 효율을 크게 높입니다.

다만 도구가 단순해도 Node 버전과 패키지 설치 상태가 어긋나면 실행이 실패하므로, 각 단계의 확인 명령을 반드시 함께 점검하는 습관이 중요합니다.

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

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

# macOS/Linux 예시
cd ~/Documents

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

cd my-first-react-app

npm install
npm run dev

아래 두 그림은 방금 진행한 설치 확인, 프로젝트 생성, 개발 서버 실행 과정을 하나의 피드백 루프로 다시 묶어 보여줍니다.

명령을 외우기보다 어느 단계에서 오류가 나는지 분리해서 확인하는 용도로 읽으면 됩니다.

VS Code로 프로젝트 열기

이제 실행 중인 리액트 프로젝트를 VS Code에서 열어 코드를 확인해 볼 차례입니다.

VS Code의 탐색기(Explorer)에서 my-first-react-app 폴더의 구조를 확인할 수 있습니다.

src 폴더 안에 있는 App.jsx 파일을 열어보면 리액트 컴포넌트 코드를 볼 수 있습니다.

이 코드를 수정하고 저장하면 Vite가 변경된 모듈을 감지합니다. create-vite의 React 템플릿에는 React Fast Refresh가 미리 구성되어 있어 지원되는 변경은 전체 페이지를 다시 불러오지 않고 빠르게 반영되며, 변경 종류에 따라 전체 새로고침이 일어날 수도 있습니다.

개발 환경을 갖출 때는 설치가 끝났다는 사실보다 저장한 코드가 개발 서버와 브라우저에 바로 반영되는 루프를 확인하는 것이 중요합니다.

현재 폴더와 실행 중인 터미널 확인하기

npm run dev는 서버가 돌아가는 동안 터미널을 계속 사용합니다. 그 터미널에 다음 명령을 이어 입력하는 대신 새 터미널을 열거나 에디터의 폴더 열기를 사용합니다. 새 터미널에서도 프로젝트 루트의 package.json이 보이는지 먼저 확인하세요. Ctrl+C로 서버를 끝내면 편집 파일은 남지만 해당 주소의 화면 제공은 중단됩니다.

혼자 오류 경계를 찾기

node와 npm 버전은 나오지만 npm run dev에서 package.json을 찾지 못한다는 오류가 났습니다. Vite 프로젝트 생성과 설치는 성공했고, 새 터미널은 프로젝트의 상위 폴더에 있습니다. Node를 다시 설치해야 하나요? 별도로 서버가 실행 중인데 화면 주소를 직접 5173으로 입력했다면 무엇부터 대조할까요?

이 루프가 잡히면 다음 절에서 src/App.jsx를 수정하며 첫 화면을 직접 바꿔볼 수 있습니다.