01 개발 환경 세팅 - woowacourse-teams/2026-jachwi-sunbae GitHub Wiki

개요

"빌드가 안 되는데, 아무도 못 고쳐요." Vite나 Next.js로 시작하면 명령어 하나로 개발 서버가 뜬다. 편하지만, 그 안에서 무슨 일이 일어나는지는 한 번도 열어보지 않는다. 그러다 빌드가 깨지거나 번들이 비대해졌을 때, 어디를 봐야 하는지 아무도 모른다. 번들링은 프론트엔드 환경의 근간인데, 지금 직접 구성해보지 않으면 앞으로도 열어볼 기회가 오지 않는다.

완료 조건

• Webpack 기반의 React & TypeScript 프로젝트 구조가 구성되어 있고, 실행 및 빌드가 가능하다.

기술 역량 목표

• Webpack 기반의 프론트엔드 프로젝트를 직접 셋업하며, 번들링에 필요한 요소를 이해하고 설정할 수 있다.
• React & TypeScript 개발에 필요한 환경을 직접 구성하고 실행해본다.

webpack

frontend/webpack/
├── build-environment.cjs
├── webpack-rules.cjs
└── webpack-plugins.cjs
└── webpack.config.cjs

기존에는 웹팩 설정을 webpack.config.js 하나에 작성했는데, 환경변수, CSS처리, 바벨, 플러그인, 운영 빌드, 개발 서버 설정이 한 파일에 모여있어 역할을 파악하기 힘들어져 분리하게 되었습니다.

build-environment.cjs

// build-environment.cjs
module.exports = {
  loadLocalEnv,
  readBuildEnvironment,
};

환경 값을 관리하는 파일입니다. 함수 두개를 내보내며 각각의 역할은 아래와 같습니다.

1. loadLocalEnv

Webpack설정에서 가장 먼저 호출되며 .env.local 파일을 읽어 환경변수에 등록합니다.

2. readBuildEnvironment

운영 모드와 개발 서버의 주소를 받아 Webpack이 사용할 환경 설정 객체를 반환합니다.

반환값	역할
apiBaseUrl	프론트엔드가 사용할 API 기본 주소
appEnvironment	development 또는 production
appVersion	현재 앱 버전
devServerPort	Webpack 개발 서버 포트
isMockingEnabled	MSW 사용 여부
mapProviderMode	demo 또는 naver 지도 사용 여부
naverMapClientId	네이버 지도 클라이언트 ID
posthogHost	PostHog 서버 주소
posthogProjectToken	PostHog 프로젝트 토큰

webpack-rules.cjs

개발 환경
CSS → style-loader → HMR

운영 환경
CSS → 별도 CSS 파일 추출(MiniCssExtractPlugin) → 압축(CssMinimizerPlugin)

TypeScript, 이미지, 동영상을 처리하고 개발환경과 운영환경에 따른 파일 종류별 변환 규칙을 관리합니다

webpack-plugins.cjs

사용하는 Webpack 플러그인을 관리합니다.

플러그인	역할
DefinePlugin	빌드 시 환경변수를 코드에 주입한다.
HtmlWebpackPlugin	번들이 연결된 index.html을 생성한다.
MiniCssExtractPlugin	운영 CSS를 별도 파일로 추출한다.
BundleAnalyzerPlugin	필요할 때 번들 구성을 분석한다.

CssMinimizerPlugin는 빌드가 끝난 이후 CSS를 압축하기 때문에 플러그인이 아닌 webpakc.config 에서 관리된다