React 앱 빌드하기

React 앱을 빌드하는 것은 개발 환경에서 실행하던 코드를 실제 웹 서버에 배포할 수 있는 형태로 변환하는 과정입니다. 이 과정을 거치면 코드는 최적화된 번들 파일로 묶이게 됩니다.

왜 빌드를 해야 하는가?

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

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

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

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

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

Vite 기반 프로젝트 빌드하기

현재 리액트 실무에서는 Vite 기반 프로젝트가 널리 사용됩니다. Vite 역시 단일 명령어로 프로덕션 빌드를 생성할 수 있고, 개발/빌드 속도가 빠르며 설정 확장이 간결합니다.

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

npm run build
# 또는
yarn build

이 명령어를 실행하면, Vite는 내부적으로 Rollup 기반 번들링을 수행해 프로젝트 루트에 dist 폴더를 생성합니다.

dist 폴더의 내용물 탐색

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

• index.html: 애플리케이션의 단일 진입점입니다. 이 파일이 로드되면 그 안에 링크된 JavaScript 파일이 실행되어 리액트 앱이 렌더링됩니다.
• assets/: 빌드된 정적 리소스(CSS, JavaScript, 이미지 등)가 해시 파일명으로 저장됩니다.
• 해시된 파일 이름 (.<hash>.js, .<hash>.css): 파일 이름에 해시 값(예: main.d2a3f5b7.js)이 포함됩니다. 이는 브라우저 캐싱 문제를 방지하기 위함입니다. 파일 내용이 변경될 때마다 해시 값이 바뀌어 브라우저가 항상 최신 버전을 다운로드하도록 합니다.
• 최소화 및 번들링: 모든 JavaScript, CSS 코드는 압축되고(minified), 여러 파일이 하나의 파일로 번들링되어 네트워크 요청 수를 줄입니다.
• 코드 스플리팅 (Code Splitting): 동적 임포트(import()) 경계 기준으로 청크를 분리하여 초기 로딩 비용을 줄입니다.
• 서비스 워커 (선택): Vite는 기본 템플릿에서 서비스 워커를 자동 생성하지 않습니다. PWA가 필요하면 vite-plugin-pwa를 추가해 명시적으로 설정합니다.

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

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

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

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

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

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

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

Vite는 vite.config.ts를 통해 빌드 동작을 직접 제어할 수 있습니다.

• 출력 제어: build.outDir, build.sourcemap, build.rollupOptions로 출력 경로/소스맵/청크 전략을 제어합니다.
• 플러그인 확장: @vitejs/plugin-react, vite-plugin-pwa 등으로 JSX 처리, PWA, 압축, 분석을 조합할 수 있습니다.
• 프레임워크 선택: SPA 중심이면 Vite, SSR/풀스택 라우팅이 핵심이면 Next.js 같은 프레임워크가 더 적합할 수 있습니다.

빌드 단계 핵심 정리와 다음 학습 포인트

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

• npm run build (또는 yarn build) 명령어로 최적화된 정적 파일을 dist 폴더에 생성합니다.
• dist 폴더는 웹 서버가 직접 서빙할 수 있고, serve 같은 도구로 로컬 검증이 가능합니다.
• 특별한 커스터마이징이 필요 없으면 Vite 기본 빌드 설정을 유지하는 것이 가장 안전합니다.

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