React 프레임워크 입문 가이드: 설치와 첫 프로젝트

React를 처음 시작하는 개발자를 위해 macOS와 Windows 개발 환경 설치, Node.js와 npm, Vite 프로젝트 생성, IDE 선택, 프로젝트 구조, 자주 만나는 오류와 학습 로드맵을 한 번에 정리했습니다.

React는 현대 웹 애플리케이션을 만들 때 가장 널리 사용되는 JavaScript 라이브러리 중 하나입니다. 대시보드, 관리자 페이지, SaaS 제품, 이커머스 사이트, 뉴스 플랫폼, 인터랙티브 프런트엔드 애플리케이션까지 다양한 영역에서 활용됩니다.

초보자에게 첫 번째 어려움은 React 자체가 아닙니다. 실제 첫 관문은 개발 환경입니다. Node.js, npm, IDE 설정, 프로젝트 생성, 로컬 실행까지 막히는 지점이 많습니다.

이 글에서는 macOS와 Windows에서 React 개발 환경을 설치하고 설정하는 방법, IDE 선택 기준, 첫 프로젝트 생성과 실행, 기본 프로젝트 구조를 단계별로 정리합니다.

1. React를 사용하기 전에 필요한 도구

React 애플리케이션을 개발하려면 다음 도구가 필요합니다.

도구용도 Node.js브라우저 밖에서 JavaScript 도구를 실행합니다. npmNode.js와 함께 설치되는 패키지 관리자입니다. Vite빠른 프로젝트 생성기이자 개발 서버입니다. IDE / 코드 에디터코드를 작성하고 프로젝트를 관리할 때 사용합니다. 브라우저React 앱을 테스트할 때 사용합니다.

현재 초보자에게 가장 추천하기 쉬운 React 프로젝트 생성 방식은 Vite를 사용하는 것입니다.

2. React, Node.js, npm, Vite 쉽게 이해하기

React

React는 사용자 인터페이스를 만들기 위한 JavaScript 라이브러리입니다. 개발자가 컴포넌트라고 부르는 재사용 가능한 UI 조각을 만들 수 있게 도와줍니다.

예시는 다음과 같습니다.

function Welcome() {
  return <h1>Hello React</h1>;
}

Node.js

Node.js는 JavaScript를 브라우저 안에서만이 아니라 내 컴퓨터에서도 실행할 수 있게 해줍니다. React 개발 도구는 Node.js에 의존합니다.

npm

npm은 Node.js와 함께 제공되는 기본 패키지 관리자입니다. React, Vite, TypeScript, 그 밖의 의존성 라이브러리를 프로젝트에 내려받습니다.

자주 사용하는 npm 명령은 다음과 같습니다.

npm install
npm run dev
npm run build

Vite

Vite는 현대적인 빌드 도구입니다. React 프로젝트를 빠르게 생성하고 빠른 로컬 개발 서버를 제공합니다.

3. macOS에서 React 개발 환경 설치하기

Step 1: macOS에 Node.js 설치

공식 Node.js 웹사이트에 접속해 LTS 버전을 다운로드합니다.

추천 선택지는 다음과 같습니다.

Download Node.js LTS for macOS

다운로드 후에는 아래 순서로 진행합니다.

`.pkg` 설치 파일을 엽니다.설치 마법사의 안내를 따릅니다.설치를 완료합니다.Terminal을 엽니다.설치 여부를 확인합니다.

node -v
npm -v

예시 출력은 다음과 같습니다.

v24.x.x
10.x.x

두 명령 모두 버전 번호를 보여준다면 Node.js와 npm이 정상적으로 설치된 것입니다.

Step 2: Homebrew를 사용하는 macOS 설치 방법

Homebrew를 사용한다면 다음 명령으로 Node.js를 설치할 수 있습니다.

brew install node

결과를 확인합니다.

node -v
npm -v

초보자에게는 보통 공식 설치 프로그램이 더 쉽습니다.

Step 3: macOS에 Visual Studio Code 설치

공식 웹사이트에서 Visual Studio Code를 다운로드합니다. 설치 후 VS Code를 열고 다음 확장을 설치하면 좋습니다.

ESLintPrettierJavaScript and TypeScript NightlyAuto Rename TagReact Developer Tools 브라우저 확장

4. Windows에서 React 개발 환경 설치하기

Step 1: Windows에 Node.js 설치

공식 Node.js 웹사이트에 접속해 Windows LTS 설치 파일을 다운로드합니다.

추천 선택지는 다음과 같습니다.

Download Node.js LTS for Windows

다운로드 후에는 아래 순서로 진행합니다.

`.msi` 설치 파일을 실행합니다.설치 마법사를 계속 진행합니다.“Add to PATH” 옵션이 켜져 있는지 확인합니다.설치를 완료합니다.Command Prompt 또는 PowerShell을 엽니다.설치 여부를 확인합니다.

node -v
npm -v

버전 번호가 표시되면 설치가 성공한 것입니다.

Step 2: Windows Terminal 설치

Windows Terminal은 오래된 Command Prompt보다 더 나은 명령줄 경험을 제공하므로 추천합니다. 사용할 수 있는 선택지는 다음과 같습니다.

Windows Terminal
PowerShell
Command Prompt
Git Bash

초보자에게는 PowerShell 또는 Windows Terminal이면 충분합니다.

Step 3: Windows에 Visual Studio Code 설치

Visual Studio Code를 다운로드하고 설치합니다. 추천 확장은 다음과 같습니다.

ESLintPrettierAuto Rename TagPath IntellisenseReact Developer Tools 브라우저 확장

5. React 개발에 추천하는 IDE

1. Visual Studio Code

초보자에게 가장 좋은 선택입니다.

장점은 다음과 같습니다.

무료입니다.가볍습니다.확장 생태계가 매우 큽니다.JavaScript와 TypeScript 지원이 좋습니다.통합 터미널을 제공합니다.Git 연동이 편리합니다.

추천 대상은 다음과 같습니다.

초보자, 학생, 프런트엔드 개발자, React 학습자

2. WebStorm

WebStorm은 JetBrains에서 만든 전문 JavaScript IDE입니다.

장점은 다음과 같습니다.

강력한 코드 자동 완성내장 리팩터링 도구뛰어난 프로젝트 탐색강력한 TypeScript 지원

추천 대상은 다음과 같습니다.

전문 개발자, 엔터프라이즈 프로젝트, 대규모 코드베이스

3. IntelliJ IDEA Ultimate

IntelliJ IDEA Ultimate도 JavaScript, TypeScript, React 개발을 지원합니다.

장점은 다음과 같습니다.

풀스택 개발자에게 적합합니다.Java와 Spring Boot 지원이 뛰어납니다.React를 백엔드 프로젝트와 함께 사용할 때 유용합니다.

추천 대상은 다음과 같습니다.

Spring Boot + React를 사용하는 풀스택 개발자

4. Cursor

Cursor는 VS Code 기반의 AI 코드 에디터입니다.

장점은 다음과 같습니다.

AI 코딩 지원코드 설명에 유용함초보자가 React 문법을 배울 때 도움컴포넌트 생성과 리팩터링에 유용함

추천 대상은 다음과 같습니다.

AI 지원 코딩을 원하는 개발자

6. Vite로 첫 React 프로젝트 만들기

macOS에서는 Terminal, Windows에서는 PowerShell을 엽니다. 프로젝트를 만들고 싶은 폴더로 이동합니다.

예시는 다음과 같습니다.

cd Desktop

React 프로젝트를 생성합니다.

npm create vite@latest my-react-app

다음과 같은 선택 질문이 표시됩니다.

Select a framework:
React

Select a variant:
JavaScript

초보자라면 다음을 선택합니다.

React
JavaScript

처음부터 TypeScript를 배우고 싶다면 다음을 선택합니다.

React
TypeScript

7. 프로젝트 폴더로 이동하기

cd my-react-app

의존성을 설치합니다.

npm install

개발 서버를 시작합니다.

npm run dev

다음과 비슷한 출력이 표시됩니다.

Local: http://localhost:5173/

브라우저에서 해당 주소를 엽니다. 이제 첫 React 앱이 실행된 것입니다.

8. React 프로젝트 구조 이해하기

Vite React 프로젝트는 보통 다음과 같은 구조를 가집니다.

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

node_modules

이 폴더에는 설치된 패키지가 들어 있습니다. 이 폴더를 직접 수정하지 마세요.

public

정적 파일을 여기에 둘 수 있습니다. 예시는 다음과 같습니다.

favicon
robots.txt
static images

src

주요 소스 코드 폴더입니다. 대부분의 React 코드는 이곳에 작성합니다.

App.jsx

메인 React 컴포넌트입니다.

function App() {
  return (
    <div>
      <h1>Hello React</h1>
      <p>This is my first React project.</p>
    </div>
  );
}

export default App;

main.jsx

이 파일은 React를 HTML 페이지에 연결합니다.

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.jsx';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

package.json

프로젝트 정보, 의존성, 명령어를 관리하는 파일입니다. 중요한 부분은 다음과 같습니다.

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "preview": "vite preview"
}

9. 유용한 npm 명령어

개발 서버 시작

npm run dev

애플리케이션을 개발하는 동안 사용합니다.

프로덕션 파일 빌드

npm run build

최적화된 프로덕션 파일을 `dist` 폴더에 생성합니다.

프로덕션 빌드 미리보기

npm run preview

프로덕션 빌드를 로컬에서 테스트합니다.

패키지 설치

npm install package-name

예시는 다음과 같습니다.

npm install axios

패키지 제거

npm uninstall package-name

10. 첫 React 페이지 수정하기

`src/App.jsx`를 엽니다. 기존 코드를 다음 코드로 바꿉니다.

function App() {
  return (
    <main>
      <h1>My First React App</h1>
      <p>React is ready. The front-end engine is alive.</p>
      <button>Click Me</button>
    </main>
  );
}

export default App;

파일을 저장하면 브라우저가 자동으로 업데이트됩니다. 이 자동 업데이트 기능을 Hot Module Replacement라고 부릅니다.

11. 간단한 React 컴포넌트 만들기

`src` 폴더 안에 새 파일을 만듭니다.

Header.jsx

다음 코드를 추가합니다.

function Header() {
  return (
    <header>
      <h1>React Beginner Blog</h1>
      <p>Learning React step by step</p>
    </header>
  );
}

export default Header;

이제 `App.jsx`를 열고 import합니다.

import Header from './Header.jsx';

function App() {
  return (
    <main>
      <Header />
      <p>This is my first component-based React page.</p>
    </main>
  );
}

export default App;

이것이 React의 핵심 아이디어입니다. 페이지를 컴포넌트를 조합해 만드는 방식입니다.

12. 초보자에게 추천하는 VS Code 설정

프로젝트 안에 `.vscode` 폴더를 만듭니다. 그 안에 다음 파일을 만듭니다.

settings.json

다음 내용을 추가합니다.

{
  "editor.formatOnSave": true,
  "editor.tabSize": 2,
  "files.autoSave": "afterDelay",
  "javascript.updateImportsOnFileMove.enabled": "always"
}

이 설정은 코딩을 더 부드럽게 만들고 작은 포맷팅 실수를 줄여줍니다.

13. Prettier 설치하기

Prettier는 코드를 자동으로 정리해 주는 도구입니다. 다음 명령으로 설치합니다.

npm install -D prettier

다음 파일을 만듭니다.

.prettierrc

아래 내용을 추가합니다.

{
  "singleQuote": true,
  "semi": true,
  "tabWidth": 2
}

이제 코드 스타일을 일관되게 유지할 수 있습니다.

14. ESLint 설치하기

ESLint는 코드 문제를 찾아주는 도구입니다. 많은 Vite React 템플릿에는 이미 ESLint 설정이 포함되어 있습니다. 프로젝트에 `eslint.config.js`가 있다면 다음 명령을 실행할 수 있습니다.

npm run lint

lint 설정이 없다면 프로젝트가 커진 뒤 추가해도 됩니다. 초보자는 먼저 다음 개념에 집중하는 것이 좋습니다.

components
props
state
events
routing
API calls

15. 초보자가 자주 만나는 오류와 해결 방법

오류: npm is not recognized

이 오류는 보통 Node.js가 PATH에 추가되지 않았다는 뜻입니다. 해결 방법은 다음과 같습니다.

Node.js를 다시 설치합니다.“Add to PATH”가 체크되어 있는지 확인합니다.Terminal을 다시 시작합니다.아래 명령을 실행합니다.

node -v
npm -v

오류: command not found: npm

macOS에서는 Node.js가 올바르게 설치되지 않았을 때 이 문제가 발생할 수 있습니다. 먼저 다음 명령을 확인합니다.

node -v
npm -v

버전이 표시되지 않으면 공식 설치 프로그램으로 Node.js를 다시 설치합니다.

오류: port 5173 already in use

다른 앱이 Vite 포트를 사용하고 있다는 뜻입니다. 다음 명령으로 다른 포트를 지정합니다.

npm run dev -- --port 3000

그다음 아래 주소를 엽니다.

http://localhost:3000

오류: Cannot find module

의존성이 설치되지 않았을 수 있습니다. 다음 명령을 실행합니다.

npm install

그다음 다시 실행합니다.

npm run dev

프로젝트 폴더를 이동한 뒤 오류가 나는 경우

`node_modules`와 `package-lock.json`을 삭제한 뒤 다시 설치합니다.

rm -rf node_modules package-lock.json
npm install

Windows PowerShell에서는 다음 명령을 사용합니다.

Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

16. JavaScript와 TypeScript 중 초보자는 무엇을 선택해야 할까?

JavaScript를 선택하면 좋은 경우

프로그래밍이 처음입니다.React를 빠르게 배우고 싶습니다.HTML, CSS, JavaScript를 아직 배우는 중입니다.

TypeScript를 선택하면 좋은 경우

기본 JavaScript를 이미 알고 있습니다.더 안전한 코드를 원합니다.엔터프라이즈 프로젝트를 계획하고 있습니다.더 나은 IDE 자동 완성을 원합니다.

추천 학습 경로는 다음과 같습니다.

JavaScript 먼저 → React 기본기 → TypeScript 나중에

17. 추천 학습 로드맵

Step 1: 웹 기본기

다음을 학습합니다.

HTML
CSS
JavaScript
DOM basics

Step 2: React 기본기

다음을 학습합니다.

Components
JSX
Props
State
Events
Conditional rendering
List rendering

Step 3: React 프로젝트 기술

다음을 학습합니다.

React Router
API calls with fetch or axios
Form handling
Environment variables
Component structure

Step 4: 실전 프로젝트

다음 프로젝트를 만들어 봅니다.

Todo app
Blog list page
News card UI
Admin dashboard
Login page UI
API-based search page

Step 5: 배포

다음을 학습합니다.

npm run build
Netlify
Vercel
Static hosting
Nginx deployment

18. 기본 React 개발 워크플로

일반적인 React 개발 흐름은 다음과 같습니다.

Create project
Install dependencies
Run local server
Edit components
Test in browser
Build production files
Deploy

명령어 요약은 다음과 같습니다.

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

19. 초보자에게 추천하는 프로젝트 예시

간단한 뉴스 카드 페이지를 만들어 보세요. 예시 컴포넌트는 다음과 같습니다.

function NewsCard({ title, category, summary }) {
  return (
    <article>
      <h2>{title}</h2>
      <p>{category}</p>
      <p>{summary}</p>
    </article>
  );
}

export default NewsCard;

`App.jsx`에서 다음처럼 사용합니다.

import NewsCard from './NewsCard.jsx';

function App() {
  return (
    <main>
      <h1>Latest Tech News</h1>

      <NewsCard
        title="React Beginner Guide"
        category="Frontend"
        summary="Learn how to set up and run your first React project."
      />
    </main>
  );
}

export default App;

이 작은 예시는 React의 세 가지 중요한 아이디어를 알려줍니다.

Component reuse
Props
Page composition

20. 결론

React는 강력한 프런트엔드 기술이지만, 초보자가 처음부터 고급 주제로 너무 빨리 들어갈 필요는 없습니다. 먼저 깔끔한 개발 환경을 만들고, Node.js와 npm이 어떻게 동작하는지 이해하고, Vite React 프로젝트를 생성한 뒤 기본 프로젝트 구조를 익히는 것이 중요합니다.

초보자에게 가장 중요한 명령어는 다음과 같습니다.

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

간단한 React 프로젝트를 생성하고, 실행하고, 수정하고, 구조를 이해할 수 있다면 이제 컴포넌트, props, state, routing, API 호출, 실전 애플리케이션 개발로 넘어갈 준비가 된 것입니다.

React 개발은 환경 설정에서 시작하지만, 작은 컴포넌트들이 살아 있는 인터페이스로 조합될 때 진짜 재미가 시작됩니다.

React 프레임워크 입문 가이드: 설치, 환경 설정, IDE와 첫 프로젝트

1. React를 사용하기 전에 필요한 도구

2. React, Node.js, npm, Vite 쉽게 이해하기

3. macOS에서 React 개발 환경 설치하기

4. Windows에서 React 개발 환경 설치하기

5. React 개발에 추천하는 IDE

6. Vite로 첫 React 프로젝트 만들기

7. 프로젝트 폴더로 이동하기

8. React 프로젝트 구조 이해하기

9. 유용한 npm 명령어

10. 첫 React 페이지 수정하기

11. 간단한 React 컴포넌트 만들기

12. 초보자에게 추천하는 VS Code 설정

13. Prettier 설치하기

14. ESLint 설치하기

15. 초보자가 자주 만나는 오류와 해결 방법

16. JavaScript와 TypeScript 중 초보자는 무엇을 선택해야 할까?

17. 추천 학습 로드맵

18. 기본 React 개발 워크플로

19. 초보자에게 추천하는 프로젝트 예시

20. 결론

댓글