icon
11장 : 배포와 다음 단계

React 앱 빌드하기

React 앱을 빌드하는 것은 개발 환경에서 실행되던 코드를 실제 웹 서버에 배포할 수 있는 형태로 변환하는 과정을 의미합니다. 이 과정을 통해 여러분의 코드는 최적화되고 효율적인 번들 파일로 묶이게 됩니다.


왜 빌드를 해야 하는가?

개발 중에는 npm start (또는 yarn start) 명령어를 사용하여 개발 서버를 실행했습니다. 이 개발 서버는 다음과 같은 특징을 가집니다.

  • 빠른 개발 환경: 코드 변경 시 즉시 반영되는 HMR(Hot Module Replacement) 기능 등을 제공하여 개발 생산성을 높입니다.
  • 다양한 개발 도구 포함: 소스 맵(Source Map) 등 디버깅에 필요한 정보가 포함되어 있습니다.
  • 최적화되지 않음: 번들 크기가 크고, 불필요한 공백이나 주석 등이 그대로 포함되어 있어 실제 서비스에 적합하지 않습니다.

반면, 프로덕션 환경에 배포하기 위한 빌드(Build) 과정은 다음과 같은 목표를 가집니다.

  • 최적화: JavaScript, CSS, HTML 파일을 최소화(Minification)하여 파일 크기를 줄이고, 불필요한 코드(예: 개발자 도구 관련 코드)를 제거합니다.
  • 번들링: 여러 개의 작은 파일들을 하나 또는 몇 개의 큰 파일로 묶어 브라우저의 네트워크 요청 수를 줄입니다.
  • 크로스 브라우징 호환성: Babel 등을 이용하여 최신 JavaScript 문법을 구형 브라우저에서도 동작하도록 변환(Transpilation)합니다.
  • 성능 향상: 이미지를 최적화하거나, 코드 스플리팅(Code Splitting)을 적용하는 등 다양한 기법을 통해 로딩 속도를 향상시킵니다.
  • 정적 파일 생성: 웹 서버가 직접 서빙할 수 있는 HTML, CSS, JavaScript, 이미지 등의 정적 파일을 생성합니다.

결론적으로, 빌드 과정은 개발된 애플리케이션을 최종 사용자에게 빠르고 안정적으로 제공하기 위한 필수적인 단계입니다.


create-react-app 기반 프로젝트 빌드하기

대부분의 리액트 초보자는 create-react-app(CRA)으로 프로젝트를 시작합니다. CRA는 복잡한 빌드 설정을 미리 다 해두었기 때문에, 여러분은 단 하나의 명령어로 프로덕션 빌드를 생성할 수 있습니다.

빌드 명령:

여러분의 리액트 프로젝트 루트 디렉토리에서 다음 명령어를 실행합니다.

npm run build
# 또는
yarn build

이 명령어를 실행하면, CRA는 내부적으로 Webpack과 Babel을 사용하여 프로젝트를 빌드하고, build 라는 새로운 폴더를 생성합니다.

build 폴더의 내용물 탐색

빌드가 완료되면 프로젝트 루트에 build/ 폴더가 생성되고, 그 안에 다음과 같은 파일들이 생성됩니다.

build/
├── index.html                  // 앱의 진입점 역할을 하는 HTML 파일
├── static/
│   ├── css/                    // CSS 파일 (최소화 및 해싱)
│   │   └── main.<hash>.css
│   ├── js/                     // JavaScript 파일 (최소화, 번들링, 해싱)
│   │   ├── main.<hash>.js
│   │   ├── 2.<hash>.chunk.js   // 코드 스플리팅된 청크 파일 (필요 시)
│   │   └── ...
│   ├── media/                  // 이미지, 폰트 등 정적 미디어 파일
│   │   └── logo.<hash>.png
│   └── ...
├── manifest.json               // PWA (Progressive Web App)를 위한 웹 앱 매니페스트
├── service-worker.js           // PWA를 위한 서비스 워커 (캐싱, 오프라인 지원 등)
└── robots.txt                  // 검색 엔진 크롤러 제어

주요 특징

  • index.html: 애플리케이션의 단일 진입점입니다. 이 파일이 로드되면 그 안에 링크된 JavaScript 파일이 실행되어 리액트 앱이 렌더링됩니다.
  • static/: 빌드된 모든 정적 파일(CSS, JavaScript, 이미지 등)이 이 폴더 아래에 구조화되어 저장됩니다.
  • 해시된 파일 이름 (.<hash>.js, .<hash>.css): 파일 이름에 해시 값(예: main.d2a3f5b7.js)이 포함됩니다. 이는 브라우저 캐싱 문제를 방지하기 위함입니다. 파일 내용이 변경될 때마다 해시 값이 바뀌어 브라우저가 항상 최신 버전을 다운로드하도록 합니다.
  • 최소화 및 번들링: 모든 JavaScript, CSS 코드는 압축되고(minified), 여러 파일이 하나의 파일로 번들링되어 네트워크 요청 수를 줄입니다.
  • 코드 스플리팅 (Code Splitting): CRA는 기본적으로 일정 크기 이상의 모듈이나 동적으로 임포트되는 모듈을 별도의 청크(chunk) 파일로 분리하여 초기 로딩 시간을 단축합니다.
  • 서비스 워커 (Service Worker): CRA는 기본적으로 PWA(Progressive Web App) 기능을 활성화하여 service-worker.js 파일을 생성합니다. 이는 오프라인 지원 및 캐싱 전략을 제공하여 앱의 로딩 속도와 안정성을 향상시킵니다. (이 기능이 필요 없다면 index.js에서 serviceWorkerRegistration.unregister()로 비활성화할 수 있습니다.)

빌드된 앱 로컬에서 테스트하기

build 폴더는 순수한 정적 파일로 구성되어 있으므로, 어떤 정적 파일 서버로도 서빙할 수 있습니다. 로컬에서 빌드된 앱을 테스트하려면 간단한 정적 파일 서버를 사용할 수 있습니다.

가장 흔한 방법은 serve 패키지를 사용하는 것입니다.

  1. serve 패키지 설치 (전역 또는 프로젝트)

    npm install -g serve
    # 또는
    yarn global add serve

    (프로젝트 단위로 설치하려면 -g를 제거하고 npm install servenpx serve 사용)

  2. build 폴더 서빙: 프로젝트 루트 디렉토리에서 다음 명령어를 실행합니다.

    serve -s build
    # 또는 (yarn 사용 시)
    npx serve -s build

    이 명령어는 build 폴더의 내용을 정적 파일 서버로 제공하고, 일반적으로 http://localhost:3000과 같은 주소로 접근할 수 있게 해줍니다.

로컬 서버로 빌드된 앱에 접속하여 모든 기능이 정상적으로 동작하는지, 스타일이 깨지지 않는지 등을 최종적으로 확인해야 합니다. 개발 서버와는 다르게 빌드된 앱에서는 개발자 도구 콘솔에 개발 관련 경고나 에러가 줄어든 것을 확인할 수 있습니다.


빌드 설정 커스터마이징 (고급)

create-react-app은 기본적으로 대부분의 빌드 설정을 숨겨두어(zero-configuration) 편리하지만, 때로는 특정 요구사항을 위해 빌드 설정을 직접 수정해야 할 필요가 있습니다.

  • Eject: CRA 프로젝트를 생성하고 npm run eject (또는 yarn eject) 명령어를 실행하면, CRA가 숨겨두었던 모든 Webpack, Babel 등의 설정 파일들이 프로젝트 루트로 노출됩니다. 이제 이 파일들을 직접 수정할 수 있습니다.
    • 장점: 완벽한 제어권.
    • 단점: 다시 CRA의 업데이트 혜택을 받기 어려워지며, 모든 빌드 환경 설정을 직접 관리해야 하는 부담이 생깁니다. (초보자에게는 권장하지 않음)
  • craco 또는 react-app-rewired: eject 없이 CRA의 빌드 설정을 확장하거나 오버라이드할 수 있게 해주는 라이브러리들입니다. eject의 단점을 피하면서 유연성을 제공합니다.
    • 장점: CRA의 유지보수 용이성을 해치지 않으면서 설정 커스터마이징 가능.
    • 단점: 추가 라이브러리 학습 및 설정 파일 관리 필요.
  • Next.js, Vite 등 다른 프레임워크/번들러 사용: 만약 처음부터 SPA 이상의 기능(서버 사이드 렌더링, 정적 사이트 생성 등)이나 더 빠른 개발 환경을 고려한다면, Next.js, Remix, Gatsby, Vite 등과 같은 프레임워크나 번들러를 고려할 수 있습니다. 이들은 각각 고유의 빌드 프로세스와 최적화 전략을 가지고 있습니다.

요약 및 다음 단계

React 앱 빌드하기는 개발된 애플리케이션을 프로덕션 환경에 배포하기 위한 필수적인 단계입니다.

  • npm run build (또는 yarn build) 명령어를 사용하여 최적화되고 번들링된 정적 파일을 build 폴더에 생성합니다.
  • build 폴더의 내용은 웹 서버가 직접 서빙할 수 있는 형태이며, serve와 같은 도구를 통해 로컬에서 테스트할 수 있습니다.
  • 특별한 빌드 설정 커스터마이징이 필요하지 않다면 CRA의 기본 빌드 프로세스를 그대로 사용하는 것이 가장 편리합니다.

이제 여러분은 리액트 애플리케이션을 배포 가능한 형태로 만드는 방법을 이해하셨습니다.