[React 공식문서 Vol.1] 리액트 설치 및 환경 구축 완벽 가이드

콘솔로그 2025. 9. 14. 09:54

2025. 9. 14. 09:54

리액트 공식문서 짚어보기 1일차 시작하겠습니다.

오늘 해 볼 부분은 설치하기 입니다.

↓↓↓ 아래 공식문서 링크 입니다.

https://ko.react.dev/learn/installation

설치하기 – React

The library for web and native user interfaces

ko.react.dev

이 장에서는

리액트 공식문서에 따르면 React를 실행해 볼 수 있는 방법은 크게 두 가지예요.
바로 "샌드박스"와 "로컬개발환경구성"입니다.

🏝️ 샌드박스에서 실행하기

리액트는 별도의 설치 없이도 온라인 코드 에디터에서 바로 실행해 볼 수 있습니다.
예를 들어 CodeSandbox, StackBlitz, CodePen 같은 툴들이 React를 지원하기 때문에,
처음 설치 과정이 번거롭게 느껴진다면 브라우저에서 바로 코드를 작성하고 실행해볼 수 있어요.

💻 로컬 개발 환경 구성하기

하지만 결국에는 내 PC에 직접 개발 환경을 세팅하는 방법이 가장 좋아요.
이 방식은 실제 프로젝트를 만들 때도 그대로 사용할 수 있기 때문에, React를 본격적으로 배우려면 꼭 거쳐야 하는 과정입니다.

로컬 환경을 꾸미려면 보통 다음 과정이 필요합니다.

Node.js 설치
프로젝트 생성 도구 사용 (예: Create React App, Vite, Next.js 등)
코드 에디터 준비 (Visual Studio Code 추천)

1️⃣ Node.js 설치하기

React는 자바스크립트 기반 라이브러리이기 때문에 Node.js가 꼭 필요합니다.
Node.js 공식 사이트에 들어가면 LTS(Long Term Support) 버전과 Current 버전 두 가지가 보일 거예요.

LTS(Long Term Support) : 장기 지원 버전으로, 안정성과 호환성이 보장됩니다. 기업이나 프로젝트에서 실무에 가장 많이 사용해요.
Current : 최신 기능이 포함된 버전이지만, 안정성보다는 새 기능 테스트에 가깝습니다.

👉 React를 배우고 실제 프로젝트를 진행하려면 LTS 버전을 설치하는 게 안전합니다.

설치가 잘 되었는지 확인하려면 터미널에서 다음 명령어를 입력합니다:

node -v
npm -v

2️⃣ 프로젝트 생성하기

로컬에서 React 프로젝트를 시작하는 방법은 여러 가지가 있습니다.

📌 Create React App (CRA)

가장 전통적인 방식으로, 초보자도 쉽게 사용할 수 있습니다.

npx create-react-app my-app
cd my-app
npm start

npm install 따로 안 해줘도 되나?

사실 npx create-react-app my-app 명령어 안에는 이미 설치 과정이 포함되어 있어서 따로 설치할 필요가 없습니다.

여기서 사용되는 npx는 npm 패키지를 로컬에 설치하지 않아도 바로 실행할 수 있게 해주는 도구예요.

하지만, 공식문서에도 있다시피 CRA는 더 이상 사용되지 않습니다.

🛠️ Create React App(CRA)의 등장과 퇴장

🚀 CRA의 탄생 (2016년)

2016년, React 팀은 Create React App(CRA)을 처음 공개했습니다.
그 당시에는 React 앱을 새로 만들기 위한 표준적인 방법이 없었어요.

React를 시작하려면 직접 다음과 같은 도구들을 하나하나 설치하고 연결해야 했습니다.

JSX 컴파일러
Linting 도구
Hot Reloading 환경

이 과정은 굉장히 까다롭고 복잡했습니다.
그래서 커뮤니티에서는 자주 사용하는 설정을 묶어 보일러플레이트(boilerplate)를 만들었지만,
업데이트가 어렵고 설정이 조각나 있어서 React 팀이 새로운 기능을 배포하기 힘들었죠.

CRA는 이런 문제를 해결했습니다.
여러 도구를 하나의 권장 설정으로 통합해 주었고,
React 팀이 Fast Refresh 지원, Hooks Lint 규칙 같은 새로운 기능을
쉽게 많은 사용자에게 배포할 수 있도록 도와주었습니다.

🛑 CRA의 한계와 지원 종료

CRA는 초보자가 React를 쉽게 시작할 수 있도록 큰 역할을 했습니다.
하지만 시간이 지나면서 한계가 뚜렷해졌습니다.

빌드 속도가 느려 대규모 앱에는 비효율적
최신 개발 트렌드(예: 서버 사이드 렌더링, 코드 스플리팅 등) 반영이 어려움
유지보수 담당자가 사라지면서 업데이트 정체

React 팀은 CRA를 프레임워크로 발전시켜 문제를 해결할 수도 있었지만,
이미 Next.js, Remix, Vite 같은 강력한 대안들이 자리를 잡은 상황이었습니다.

결국 React 팀은 CRA의 지원 종료를 결정했습니다.
이제 새로운 앱을 설치할 때 CRA를 사용하면 지원 종료 경고 메시지가 표시됩니다.

그래서 요새 대부분 마이그레이션을 하는 추세예요.

🧐 CRA를 꼭 알아야 마이그레이션 할 수 있을까?

1. CRA를 몰라도 마이그레이션 가능 ✅

CRA 프로젝트는 기본적으로 Webpack + Babel 기반의 설정을 감춰둔 구조입니다.
실제 마이그레이션은 대부분 의존성 패키지 교체 + 빌드 도구 전환 작업이에요.
그래서 CRA 내부 설정을 다 알 필요는 없습니다.

즉, “CRA가 내부적으로 어떻게 동작하는지”까지 알 필요는 없어요.

2. 하지만 CRA 구조를 조금 알면 이득 ⬆️

CRA는 src/, public/ 폴더 구조와 index.js 진입 파일 등 표준 프로젝트 구조를 가지고 있어요.
이 구조를 이해하면 Vite나 Next.js로 옮길 때 파일 매핑이 훨씬 수월합니다.
예를 들어:
- CRA의 public/index.html → Vite의 index.html
- CRA의 index.js → Vite/Next.js의 진입점(main.jsx or _app.tsx)

3. 마이그레이션 접근 방식

CRA → Vite
- 폴더 구조 비슷, 비교적 단순
- react-scripts 제거 후 Vite 설정 추가
- babel 대신 Vite의 esbuild/rollup을 사용
CRA → Next.js
- 라우팅, 서버 기능이 다르므로 단순 교체보다는 프로젝트 구조 개편 필요
- 하지만 CRA 내부를 몰라도 Next.js 공식 문서의 “마이그레이션 가이드”만 따르면 충분

🚚 CRA에서 마이그레이션 하기

CRA의 지원이 종료되면서, 이제는 새로운 프로젝트를 시작하거나 기존 앱을 이어가려면 프레임워크 또는 빌드 도구로 옮겨야 합니다.

1️⃣ 프레임워크로 마이그레이션 하기 (추천 ⭐)

React 팀은 새로운 앱을 만들 때 프레임워크 기반으로 시작하는 걸 권장합니다.
추천되는 모든 프레임워크는 다음 특징을 지원합니다:

클라이언트 사이드 렌더링(CSR)
단일 페이지 앱(SPA)
CDN 또는 정적 호스팅 서비스에 서버 없이 배포 가능

즉, CRA로 하던 방식은 그대로 유지하면서도 프레임워크가 제공하는 강력한 기능들을 더 활용할 수 있습니다.

📌 공식 마이그레이션 가이드:

2️⃣ 빌드 도구로 마이그레이션하기 (커스텀 세팅이 필요할 때)

만약 앱이 특수한 제약 조건을 가지고 있거나, 직접 프레임워크를 만들고 싶은 경우, 혹은 React가 처음부터 어떻게 동작하는지 배우고 싶다면 빌드 도구를 직접 선택할 수 있습니다.

대표적인 빌드 도구:

Vite → 빠른 빌드, 간단한 설정
Parcel → 제로 설정(Zero-config) 철학
RSBuild → 최신 Rust 기반 빌드 도구

📌 공식 마이그레이션 가이드:

또한 React 팀은 Vite, Parcel, RSBuild로 앱을 새로 시작하는 데 도움을 주는 문서를 별도로 추가해 두었습니다.

⚡ Vite

요즘은 빠른 빌드 속도와 가벼운 설정 때문에 Vite를 많이 사용합니다.

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

1. Vite 설치 및 프로젝트 생성 방법

방법 1: npx 사용

npx create-vite@latest my-app

CRA처럼 패키지를 임시로 다운로드해서 실행
프로젝트 폴더(my-app) 생성 후 기본 세팅 완료
이후 cd my-app → npm install → npm run dev

방법 2: npm init 사용 (최신 권장)

npm create vite@latest my-app

사실상 npx와 동일한 기능
최신 Vite 문서에서는 이 방법을 더 권장
이유: npm create <패키지>가 npx보다 명확하게 최신 버전을 설치해 줌

2. 실행 과정

프로젝트 생성: npm create vite@latest my-app
디렉터리 이동: cd my-app
의존성 설치: npm install
개발 서버 실행: npm run dev

CRA와 달리 Vite는 프로젝트 생성 후 의존성을 별도로 설치해야 합니다.
CRA는 npx create-react-app 명령어 안에서 자동으로 설치까지 해주지만, Vite는 한 단계가 추가되는 구조예요.

🌐 Next.js

서버 사이드 렌더링과 라우팅까지 제공하는 프레임워크를 쓰고 싶다면 Next.js가 좋아요.

npx create-next-app@latest my-app
cd my-app
npm run dev

3️⃣ 코드 에디터 준비

개발을 편하게 하려면 Visual Studio Code(VS Code) 같은 코드 에디터를 설치하는 게 좋아요.
여기에 React 관련 확장 프로그램(예: ES7+ React/Redux/React-Native snippets, Prettier 등)을 추가하면 더 편리합니다.

🛠️ Custom Toolchain

우선 알기 쉽게 간단히 요약하고 아래에 자세히 한번 알아볼게요.

⚙️ React 개발 환경의 역할별 도구 구조

React 앱을 개발할 때, 여러 도구가 각자 역할을 나눠 수행합니다.
한눈에 이해하기 쉽게 기호와 단계로 정리해 보겠습니다.

📦 패키지 매니저
└─ npm / yarn / pnpm
   → 프로젝트 생성, 라이브러리 설치/관리

📝 컴파일러(Transpiler)
└─ Babel / TypeScript / esbuild
   → JSX, 최신 JS, TS를 브라우저가 이해할 수 있는 JS로 변환

📦 번들러(Bundler)
└─ Webpack / esbuild / Rollup / Parcel
   → 여러 파일(JS, CSS, 이미지)을 하나 또는 몇 개로 묶고 최적화

💻 개발 서버(Dev Server)
└─ CRA: react-scripts start
└─ Vite: vite dev server
└─ Next.js: next dev
   → 코드 변경 시 자동 반영, Hot Reload 지원

🎨 Lint & Formatter
└─ ESLint / Prettier
   → 코드 스타일 검증, 문법 오류 확인

🧪 테스트 도구
└─ Jest / Vitest
   → 단위 테스트, 통합 테스트 수행

📦 패키지 매니저란?

Node.js를 설치하면 함께 npm(Node Package Manager)이라는 패키지 매니저가 따라옵니다.
패키지 매니저는 리액트 같은 라이브러리를 설치하고 관리해 주는 도구예요.

대표적으로는 다음 세 가지가 있습니다:

npm
- Node.js 기본 패키지 매니저
- 따로 설치할 필요 없음 (Node 설치 시 자동 포함)
- 가장 널리 사용됨
yarn
- Meta(구 Facebook)에서 만든 패키지 매니저
- npm보다 속도가 빠르고, 설치 과정에서 안정성을 강조
- 팀 단위 프로젝트에서 종종 사용됨
pnpm
- 디스크 공간을 효율적으로 쓰는 최신 패키지 매니저
- 동일한 패키지를 여러 프로젝트에서 공유 가능
- 속도도 빠르고 최근에 점점 인기가 올라가는 중

👉 처음 시작하는 단계라면 npm 그대로 사용해도 충분합니다.
필요에 따라 yarn이나 pnpm을 선택할 수도 있다는 정도만 알고 계시면 돼요.

그럼 패키지 매니저 선택 시점은 언제일까요?

📦 패키지 매니저 선택 시점

보통 React 프로젝트를 시작할 때 패키지 매니저는 프로젝트 생성 직전에 선택합니다.

1️⃣ 프로젝트 생성 도구 실행 전

CRA, Vite, Next.js 등 프로젝트 생성 명령어를 실행하기 전에
자신이 사용할 패키지 매니저를 결정합니다.
예시:
- npm → CRA: npx create-react-app my-app
- yarn → CRA: yarn create react-app my-app
- pnpm → Vite: pnpm create vite@latest my-app

패키지 매니저에 따라 생성 후 설치 명령어(npm install / yarn / pnpm install)가 달라집니다.

2️⃣ 프로젝트 생성 후

프로젝트 생성 과정에서 패키지 매니저가 설치와 의존성 관리를 담당합니다.
이후 모든 패키지 추가, 삭제, 실행 명령은 선택한 패키지 매니저로 실행합니다.
- 예: npm install axios vs yarn add axios vs pnpm add axios
이미 프로젝트를 시작한 뒤 다른 매니저로 바꾸는 것도 가능하지만,
의존성 관리 방식이 달라 충돌이 생길 수 있어 추천하지 않습니다.

3️⃣ 선택 기준

팀에서 표준화된 매니저가 있다면 그걸 선택
초보자 / 단순 프로젝트 → npm
속도와 캐싱 효율 → yarn 또는 pnpm
디스크 공간 효율 → pnpm

🛠️ React에서 컴파일러란?

React 자체는 브라우저에서 바로 실행 가능한 자바스크립트 라이브러리입니다.
그런데 우리가 작성하는 코드에는 최신 자바스크립트 문법, JSX, TypeScript 등이 포함되어 있어서
브라우저가 이해하지 못하는 경우가 많아요.

이때 등장하는 것이 컴파일러(Transpiler)입니다.

컴파일러는 다음 작업을 수행합니다.

JSX → JavaScript 변환

const element = <h1>Hello, React!</h1>;

→ 브라우저가 이해할 수 있는 JS 코드로 변환
최신 JS 문법 변환
- ES6+ 문법 (예: import, const, arrow function) → 호환 가능한 코드로 변환
TypeScript → JavaScript 변환
- 타입 정보를 제거하고 순수 JS 코드로 변환

대표 컴파일러

Babel: CRA, Vite 등에서 기본적으로 사용
TypeScript Compiler(tsc): TypeScript 프로젝트에서 사용
esbuild: Vite 등 최신 빌드 도구에서 빠른 변환용

어떤 식으로 동작하냐면,

개발자 코드(JSX, TS) → 컴파일러(Babel/esbuild/tsc) → 브라우저가 이해 가능한 JS

즉, 컴파일러는 브라우저가 이해하지 못하는 코드를 변환해 주는 역할
React 개발 환경에서는 거의 항상 자동으로 설정되어 있어서 개발자가 따로 설치할 필요는 없음

🛠️ CRA vs Vite vs Next.js 컴파일러 비교

React 프로젝트를 만들 때 어떤 컴파일러가 쓰이는지에 따라 빌드 속도와 개발 경험이 달라집니다.

프로젝트 도구	기본 컴파일러	특징	주의점
CRA (Create React App)	Babel	- JSX, 최신 JS 문법을 브라우저 호환 코드로 변환 - 프로젝트 생성 시 자동 설정 - 개발 서버 Hot Reload 지원	- 빌드 속도가 비교적 느림 - 설정 커스터마이징이 제한적
Vite	esbuild + Babel	- esbuild가 빠른 변환 제공 → 개발 서버 매우 빠름 - 일부 고급 변환은 Babel 사용 - TypeScript 지원	- CRA보다 초기 설정 자유도가 높음 - 일부 Babel 플러그인 호환성 확인 필요
Next.js	Babel + SWC	- SWC(Speedy Web Compiler)로 빠른 빌드 - SSR, SSG 지원 - JSX, TS 변환 모두 처리	- SWC는 일부 고급 Babel 플러그인 미지원 - 서버 렌더링 관련 설정 필요

🛠️ 기본 컴파일러와 커스터마이징 가능 여부

1. CRA (Create React App)

기본 컴파일러: Babel
변경 가능 여부: 제한적
- CRA는 설정이 숨겨져 있음(react-scripts 내부에 설정)
- 직접 Babel을 교체하거나 Webpack 설정을 바꾸려면 eject 해야 함
- eject 후에는 모든 설정이 프로젝트 안으로 풀리지만, 되돌릴 수 없음 → 관리 부담 ↑

npm run eject

대부분은 CRA 기본 Babel 설정 그대로 사용하는 것이 권장

2. Vite

기본 컴파일러: esbuild + Babel
변경 가능 여부: 자유로움
- Vite는 설정 파일(vite.config.js)을 직접 수정 가능
- 필요하면 esbuild 대신 Babel로 전환하거나 플러그인을 추가 가능
- 설정 자유도가 높아서 커스텀 툴체인에 적합

3. Next.js

기본 컴파일러: Babel + SWC
변경 가능 여부: 부분적으로 가능
- Next.js는 SWC를 기본으로 사용하여 빠른 빌드 제공
- SWC 대신 Babel로 강제 전환 가능 (next.config.js 설정)
- 하지만 SWC 최적화 일부를 포기해야 함

Vite가 가장 유연하게 컴파일러를 변경할 수 있고, CRA는 거의 못 바꾸는 수준, Next.js는 부분적 조정만 가능하다고 이해하면 됩니다.

🛠️ 번들러(Bundler)란?

React 프로젝트에서는 많은 파일과 라이브러리를 사용하게 됩니다.
브라우저는 import 같은 모듈 문법을 일부만 지원하고, 여러 개의 파일을 한 번에 로드하는 데 한계가 있어요.
이때 등장하는 것이 번들러(Bundler)입니다.

번들러의 역할:

여러 개의 JS, CSS, 이미지 파일을 하나 또는 몇 개의 파일로 묶음
브라우저가 효율적으로 읽을 수 있는 형태로 변환
필요시 최적화, 코드 스플리팅, 압축까지 수행

대표 번들러

번들러	특징	사용 예시
Webpack	가장 널리 쓰이는 번들러, 플러그인과 설정 자유도가 높음	CRA, 커스텀 프로젝트
esbuild	매우 빠른 빌드, TypeScript 지원, 최신 도구 중심	Vite 개발 서버
Rollup	라이브러리 배포에 최적화, 트리 쉐이킹(Tree Shaking) 강력	라이브러리 제작, Vite 빌드
Parcel	설정 거의 필요 없음, Zero-config	개인 프로젝트, 학습용

React 프로젝트에서 번들러 위치

개발자 코드 + 라이브러리 → 번들러(webpack/esbuild/rollup) → 브라우저가 읽는 단일/최적화된 파일

CRA: Webpack
Vite: 개발 서버 → esbuild, 빌드 시 Rollup 사용
Next.js: Webpack 기본, 빌드 최적화 가능

번들러를 직접 바꿀 수 있을까?

CRA: Webpack 설정 숨겨져 있어 어렵다(eject 필요)
Vite: 설정 파일에서 쉽게 교체/커스터마이징 가능
Next.js: Webpack 교체 가능, 일부 제한 존재

번들러는 여러 파일을 하나로 묶어 브라우저가 실행 가능하게 해주는 도구
React 프로젝트에서는 필수적인 역할
도구마다 기본 번들러가 다르고, 변경 가능 여부도 차이가 있음

🛠️ 미니파이어(Minifier)란?

미니파이어는 코드 파일의 크기를 줄여주는 도구입니다.
React 앱처럼 여러 JS, CSS 파일을 브라우저에서 로드할 때, 파일 크기가 크면 페이지 로딩 속도가 느려집니다.

미니파이어는 이를 해결하기 위해 불필요한 공백, 줄 바꿈, 주석, 변수 이름을 축약합니다.

// 원본
function sayHello(name) {
    console.log("Hello, " + name + "!");
}
sayHello("React");

↓↓↓ 미니파이 후

// 미니파이 후
function a(b){console.log("Hello, "+b+"!")}a("React");

번들링 과정에서 자동 적용: Webpack, Vite, Rollup 등 대부분 번들러가 미니파이어 기능을 포함
프로덕션 빌드 시 필수: 개발 서버에서는 가독성을 위해 적용하지 않음

목적: 코드 용량 줄여 페이지 로딩 속도 개선
언제 쓰는가: 프로덕션 빌드 시 자동 적용
개발자가 직접 건드릴 필요 거의 없음

🛠️ 테스트 러너(Test Runner)란?

테스트 러너는 작성한 테스트 코드를 실행하고 결과를 확인하는 도구입니다.
React 앱에서는 UI, 기능, 상태 관리 등이 의도대로 동작하는지 검증할 때 사용합니다.

역할

테스트 파일 실행
성공/실패 여부 출력
테스트 환경 설정 (예: DOM 시뮬레이션, Mock 데이터 제공)
테스트 보고서 생성

즉, 코드를 실제로 실행해서 기능이 올바른지 확인해주는 역할입니다.

테스트 러너	특징	React 환경 사용 예시
Jest	Facebook에서 만든 JavaScript 테스트 러너	CRA, Vite, Next.js 기본 지원, 단위/통합 테스트 가능
Vitest	Vite 친화적, 빠른 테스트	Vite 프로젝트 추천, Jest 호환 API 지원
Mocha	유연한 구조, 커스텀 가능	구버전 또는 커스텀 프로젝트에서 사용
Jasmine	BDD 스타일, 비교적 오래된 JS 테스트	과거 프로젝트 유지보수용

React에서 사용하는 방식

단위(Unit) 테스트: 함수, 컴포넌트 개별 기능 검증
통합(Integration) 테스트: 여러 컴포넌트를 함께 사용했을 때 동작 검증
UI 테스트: React Testing Library와 결합해 실제 DOM 렌더링 결과 검증

import { render, screen } from '@testing-library/react';
import App from './App';

test('renders hello message', () => {
  render(<App />);
  const heading = screen.getByText(/hello react/i);
  expect(heading).toBeInTheDocument();
});

오늘은 React 공식 문서의 설치 및 개발 환경 구성 부분을 중심으로 살펴봤습니다.
CRA, Vite, Next.js 등 다양한 프로젝트 생성 도구가 있고, 각 도구마다 기본 컴파일러와 번들러가 있다는 점을 배웠습니다.
npx create-react-app 명령어가 프로젝트 생성과 의존성 설치를 한 번에 처리해준다는 것도 확인했죠.

Vite는 최신 도구답게 빠른 빌드와 자유로운 설정이 장점이며, Next.js는 서버 사이드 렌더링까지 지원합니다.
React 환경에서는 패키지 매니저, 컴파일러, 번들러, 미니파이어, 개발 서버, 테스트 러너가 각자 역할을 나눠 프로젝트를 효율적으로 관리합니다.
특히 Jest와 같은 테스트 러너를 통해 단위 테스트와 통합 테스트를 쉽게 실행할 수 있다는 것도 실습해봤습니다.
CRA와 Vite, Next.js의 도구별 특징과 커스터마이징 가능 여부를 비교하면서, 자신에게 맞는 개발 환경을 선택하는 기준도 알 수 있었습니다.

이 과정에서 각 도구가 제공하는 편의성과, 직접 설정할 수 있는 Custom Toolchain의 장단점도 이해할 수 있었죠.
앞으로는 오늘 배운 내용을 바탕으로 실제 프로젝트를 만들고 실행해보며, 각 도구가 어떻게 동작하는지 경험해보는 것이 중요합니다.
React 개발 환경을 제대로 이해하면, 새로운 프로젝트를 시작할 때 어떤 도구를 선택하고, 효율적으로 구성할지 자신 있게 결정할 수 있습니다.

'개발 로그 > React' 카테고리의 다른 글

[React 공식문서 vol.0] 공식문서로 리액트 기본 다지기 (0)	2025.09.14
[React] SPA와 리액트: 현대 웹 개발의 핵심 기술 이해하기 (1)	2025.09.13

코딩하는퇴근길