포스트

React 개발 환경 설정 - CRA, Node, npm 완벽 가이드

Create React App(CRA)을 사용한 React 프로젝트 설정 방법과 Node.js, npm의 역할을 상세히 알아봅니다. 초보자도 쉽게 따라할 수 있는 단계별 설정 가이드를 제공합니다.

게시일
작성자 ChangSu Park
읽는 시간 10분
React 개발 환경 설정 - CRA, Node, npm 완벽 가이드

Create React App이란?

Create React App(CRA)는 React 공식 팀이 제공하는 React 애플리케이션 개발 환경 구축 도구입니다. 복잡한 설정 없이 최신 React 개발 환경을 한 번에 구성할 수 있습니다.

CRA의 주요 특징

  1. Zero Configuration
    • Webpack, Babel 등의 복잡한 설정이 자동으로 처리됩니다
    • 개발자는 코드 작성에만 집중할 수 있습니다
  2. 최신 JavaScript 기능 지원
    • ES6+ 문법을 자동으로 트랜스파일링
    • 모던 브라우저와 레거시 브라우저 모두 지원
  3. 프론트엔드 빌드 파이프라인
    • 백엔드 로직이나 데이터베이스를 처리하지 않음
    • 어떤 백엔드와도 조합 가능
  4. 프로덕션 최적화
    • 코드 압축, 번들링, 최적화 자동 처리
    • 성능 최적화된 프로덕션 빌드 제공

개발 환경 구성 요소

Node.js

Node.js는 Chrome V8 JavaScript 엔진 기반의 JavaScript 런타임 환경입니다.

Node.js의 역할

특징설명
JavaScript 실행 환경브라우저 밖에서도 JavaScript 실행 가능
서버 사이드 개발빠르고 확장성 있는 네트워크 애플리케이션 구축
개발 도구 플랫폼Babel, Webpack 등의 빌드 도구 실행 기반

React에서 Node.js가 필요한 이유

React 애플리케이션 자체는 브라우저에서 실행되므로 Node.js와 직접적인 연관은 없습니다. 하지만 다음과 같은 이유로 Node.js 설치가 필수입니다:

  • Babel: JSX를 JavaScript로 변환
  • Webpack: 모듈 번들링 및 최적화
  • Development Server: 로컬 개발 서버 실행
  • npm/npx: 패키지 관리 및 스크립트 실행

npm (Node Package Manager)

npm은 Node.js의 기본 패키지 관리자로, JavaScript 생태계에서 가장 큰 패키지 저장소입니다.

npm의 핵심 기능

1
2
3
4
5
6
7
8
9
10
11

# 패키지 설치
npm install <package-name>

# 전역 패키지 설치
npm install -g <package-name>

# 개발 의존성 패키지 설치
npm install --save-dev <package-name>

# 스크립트 실행
npm run <script-name>

npm vs npx

구분npmnpx
용도패키지 관리 및 설치패키지 실행
설치 여부로컬/전역 설치 필요임시 다운로드 후 실행
디스크 사용설치된 패키지가 디스크 차지실행 후 삭제됨
사용 예npm install reactnpx create-react-app my-app

npx의 장점:

  • 전역 설치 없이 최신 버전 실행
  • 디스크 공간 절약
  • 항상 최신 버전 사용 보장

Create React App 프로젝트 생성

1. Node.js 설치 확인

1
2
3
4
5
6
7

# Node.js 버전 확인
node --version
# v14.0.0 이상 권장

# npm 버전 확인
npm --version
# v6.0.0 이상 권장

설치가 필요한 경우: Node.js 공식 웹사이트에서 LTS 버전 다운로드

2. React 프로젝트 생성

1
2
3
4
5
6
7
8

# npx를 사용한 프로젝트 생성 (권장)
npx create-react-app my-app

# 프로젝트 디렉토리 이동
cd my-app

# 개발 서버 시작
npm start

3. 프로젝트 구조

1
2
3
4
5
6
7
8
9
10
11

my-app/
├── node_modules/       # 설치된 패키지들
├── public/             # 정적 파일
│   ├── index.html     # HTML 템플릿
│   └── favicon.ico    # 파비콘
├── src/               # 소스 코드
│   ├── App.js        # 메인 컴포넌트
│   ├── index.js      # 진입점
│   └── App.css       # 스타일
├── package.json       # 프로젝트 설정 및 의존성
└── README.md         # 프로젝트 문서

4. 개발 서버 실행

1

npm start

실행 결과:

  • 로컬 주소: http://localhost:3000
  • 브라우저가 자동으로 열림
  • React 로고가 회전하는 화면 표시
  • 코드 변경 시 자동 리로드 (Hot Reload)

주요 npm 스크립트

CRA 프로젝트에서 사용 가능한 주요 명령어:

개발 관련

1
2

# 개발 서버 시작 (localhost:3000)
npm start

빌드 및 배포

1
2
3
4
5
6

# 프로덕션 빌드 생성
npm run build

# 빌드 결과물: build/ 디렉토리
# - 압축 및 최적화된 파일
# - 배포 준비 완료 상태

테스트

1
2
3
4
5

# 테스트 실행 (watch mode)
npm test

# 테스트 커버리지 확인
npm test -- --coverage

설정 노출 (주의!)

1
2

# Webpack 설정 노출 (되돌릴 수 없음!)
npm run eject

경고: eject 명령어는 숨겨진 설정을 노출시킵니다. 한 번 실행하면 되돌릴 수 없으므로 신중히 사용하세요.

환경별 설정

개발 환경

1
2
3
4
5
6
7

# 개발 모드 실행
npm start

# 특징:
# - Source maps 포함
# - Hot Module Replacement
# - 상세한 에러 메시지

프로덕션 환경

1
2
3
4
5
6
7

# 프로덕션 빌드
npm run build

# 특징:
# - 코드 압축 (minification)
# - 파일 이름에 해시 추가
# - 최적화된 번들 크기

문제 해결 가이드

포트 충돌 문제

1
2
3
4
5

# 다른 포트로 실행 (Mac/Linux)
PORT=3001 npm start

# 다른 포트로 실행 (Windows)
set PORT=3001 && npm start

캐시 문제

1
2
3
4
5
6

# node_modules 삭제 후 재설치
rm -rf node_modules
npm install

# npm 캐시 정리
npm cache clean --force

권한 문제 (Mac/Linux)

1
2
3
4
5
6

# sudo 없이 전역 패키지 설치 설정
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# ~/.profile 또는 ~/.bashrc에 추가
export PATH=~/.npm-global/bin:$PATH

TypeScript 프로젝트 생성

1
2
3
4
5

# TypeScript 템플릿 사용
npx create-react-app my-app --template typescript

# 기존 프로젝트에 TypeScript 추가
npm install --save typescript @types/node @types/react @types/react-dom

대안 도구

Vite

1
2

# Vite를 사용한 React 프로젝트 생성
npm create vite@latest my-app -- --template react

Vite의 장점:

  • 매우 빠른 개발 서버 시작
  • 더 빠른 Hot Module Replacement
  • 최신 빌드 도구 (esbuild 사용)

Next.js

1
2

# Next.js 프로젝트 생성
npx create-next-app my-app

Next.js의 장점:

  • Server-Side Rendering (SSR)
  • 파일 기반 라우팅
  • API 라우트 내장
  • 프로덕션 최적화

모범 사례

1. 패키지 버전 관리

1
2
3
4
5
6

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "18.2.0"
  }
}

버전 표기 방식:

  • ^18.2.0: 마이너 업데이트 허용 (18.2.x, 18.3.x 등)
  • 18.2.0: 정확한 버전 고정 (18.2.0만 허용)

2. .gitignore 설정

1
2
3
4
5
6
7
8
9
10
11
12
13

# 의존성
node_modules/

# 빌드 결과물
build/

# 환경 변수
.env.local
.env.development.local
.env.production.local

# 로그
npm-debug.log*

3. 환경 변수 사용

1
2
3

# .env 파일 생성
REACT_APP_API_URL=https://api.example.com
REACT_APP_API_KEY=your-api-key

1
2

// 코드에서 사용
const apiUrl = process.env.REACT_APP_API_URL;

주의: 환경 변수명은 반드시 REACT_APP_으로 시작해야 합니다.

성능 최적화 팁

빌드 분석

1
2
3
4
5
6
7
8

# 빌드 번들 크기 분석
npm install --save-dev webpack-bundle-analyzer
npm run build -- --stats

# 또는 source-map-explorer 사용
npm install --save-dev source-map-explorer
npm run build
npx source-map-explorer 'build/static/js/*.js'

Code Splitting

1
2
3
4
5
6
7
8
9
10
11
12

// 동적 import를 사용한 코드 분할
import React, { lazy, Suspense } from 'react';

const LazyComponent = lazy(() => import('./LazyComponent'));

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <LazyComponent />
    </Suspense>
  );
}

다음 단계

Create React App 설정을 완료했다면:

  1. 컴포넌트 기초 학습: 함수형/클래스형 컴포넌트
  2. JSX 문법 이해: JavaScript + HTML
  3. Props와 State: 데이터 관리
  4. 이벤트 처리: 사용자 인터랙션
  5. 라우팅: React Router 도입

마치며

Create React App은 React 개발을 시작하는 가장 쉽고 빠른 방법입니다. 복잡한 설정 없이 바로 개발을 시작할 수 있으며, 프로덕션 배포까지 모든 과정을 지원합니다.

초기 학습 단계에서는 CRA로 시작하고, 프로젝트 요구사항이 복잡해지면 Vite나 Next.js 같은 대안 도구를 고려해보세요.

Programming, React
react cra nodejs npm
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.