Build 개념

설정 템플릿 자동 생성과 검증 시스템

왜 소스 코드가 있는데 dist(빌드 결과물)가 따로 필요한가?

🏗️ 비유로 이해하기

비유 1: 요리

소스 코드 = 레시피 + 재료
빌드 = 요리 과정
dist = 완성된 음식

	소스 코드	빌드 결과 (dist)
개발자	레시피와 재료를 보고 수정	완성된 음식만 제공
사용자	요리할 줄 모르면 못 먹음	바로 먹을 수 있음

예시:

• 소스: Button.tsx (TypeScript 코드, 사람이 읽기 좋음)
• dist: button.abc123.js (JavaScript, 브라우저가 실행 가능)

---

비유 2: 건축

소스 코드 = 설계도 + 자재
빌드 = 건축 과정
dist = 완성된 건물

설계도만으로는 살 수 없습니다! → 건축을 해야 실제 건물(dist)이 나옵니다.

---

🤔 왜 dist가 필요한가?

문제 1: 브라우저는 TypeScript를 못 읽음

소스 코드 (사람이 작성):

// Button.tsx (TypeScript)
interface ButtonProps {
  text: string;
  onClick: () => void;
}

export const Button: React.FC<ButtonProps> = ({ text, onClick }) => {
  return <button onClick={onClick}>{text}</button>;
};

브라우저: "뭐야 이거? React? FC? tsx? 모르겠는데?" ❌

빌드 결과 (브라우저가 이해):

// button.abc123.js (순수 JavaScript)
function Button(props) {
  return React.createElement('button', {
    onClick: props.onClick
  }, props.text);
}

브라우저: "오케이 이건 알겠어!" ✅

---

문제 2: 파일이 너무 많음

소스 코드 (개발 시):

web_helper/frontend/src/
├── components/
│   ├── Button.tsx
│   ├── Card.tsx
│   ├── Table.tsx
│   └── ... (100개 파일)
├── hooks/
│   ├── useDevices.ts
│   └── useProjects.ts
└── lib/
    └── utils.ts

문제: 100개 파일 = 100번 네트워크 요청 = 느림! 🐌

빌드 결과:

dist/
├── index.html
└── assets/
    ├── index.abc123.js  (모든 JS를 하나로 합침!)
    └── index.def456.css (모든 CSS를 하나로 합침!)

결과: 2-3개 파일만 다운로드 = 빠름! 🚀

---

문제 3: 코드가 너무 큼

소스 코드:

// 주석, 공백, 긴 변수명
export const MyVeryLongFunctionName = (param1: string, param2: number) => {
  // 이것은 중요한 함수입니다
  const temporaryVariable = param1 + param2;
  return temporaryVariable;
};

빌드 결과 (압축):

// 주석 제거, 변수명 축약, 공백 제거
function a(b,c){return b+c}

크기: 200KB → 50KB (75% 감소!)

---

📁 실제 구조 비교

개발 환경 (소스 코드)

web_helper/frontend/
├── src/                     ← 개발자가 작성하는 코드
│   ├── App.tsx             (TypeScript)
│   ├── components/         (React 컴포넌트)
│   └── lib/                (유틸리티)
├── package.json            (의존성 목록)
└── vite.config.ts          (빌드 설정)

사용자: 개발자만 실행: npm run dev (개발 서버) 특징:

• TypeScript, JSX 사용 가능
• Hot Reload (코드 수정하면 바로 반영)
• 느림 (파일 많음, 변환 실시간)

---

프로덕션 환경 (빌드 결과)

web_helper/frontend/dist/    ← npm run build로 생성
├── index.html              (진입점)
└── assets/
    ├── index-abc123.js     (모든 JS 합쳐짐 + 압축)
    └── index-def456.css    (모든 CSS 합쳐짐 + 압축)

사용자: 최종 사용자 (브라우저) 실행: 웹 서버 (Nginx, FastAPI 등) 특징:

• 순수 JavaScript, HTML, CSS만
• 파일 수 적음 (빠름)
• 압축됨 (크기 작음)
• 난독화됨 (보안)

---

🔄 빌드 프로세스

Step 1: 소스 코드 작성

// src/App.tsx
import { Button } from './components/Button';

function App() {
  return <Button text="클릭" />;
}

Step 2: npm run build

npm run build

## Vite가 하는 일:
## 1. TypeScript → JavaScript 변환
## 2. React JSX → 순수 함수 변환
## 3. 모든 파일 합치기 (번들링)
## 4. 압축 (minify)
## 5. 파일명에 해시 추가 (캐싱용)

Step 3: dist/ 생성

dist/
├── index.html
└── assets/
    └── index-abc123.js  (컴파일 + 번들 + 압축된 결과)

Step 4: 서버에서 제공

## app.py
from fastapi.staticfiles import StaticFiles

app.mount("/", StaticFiles(directory="web_helper/frontend/dist"))

사용자 브라우저: http://server:8000 접속 → dist/index.html 다운로드 → dist/assets/index-abc123.js 다운로드 → 실행! ✅

---

🎯 핵심 정리

왜 소스 코드와 dist가 따로 있나?

	소스 코드 (src/)	빌드 결과 (dist/)
대상	개발자	브라우저/사용자
언어	TypeScript, JSX	JavaScript
파일 수	많음 (100+)	적음 (2-3개)
크기	큼 (주석, 공백)	작음 (압축)
가독성	좋음	나쁨 (난독화)
속도	느림	빠름
수정	가능	불가능 (재빌드 필요)

비유 정리

소스 코드 = 레시피
빌드 = 요리
dist = 완성된 음식

개발자 = 레시피를 보고 요리
사용자 = 완성된 음식만 먹음

---

🛠️ 실전 예시

시나리오: 웹 UI 배포

개발 환경 (로컬)

cd web_helper/frontend

## 개발 서버 실행 (소스 코드 직접 사용)
npm run dev

## Vite가 실시간으로:
## - TypeScript를 JavaScript로 변환
## - JSX를 함수로 변환
## - Hot Reload 제공

## 결과: http://localhost:5173 (개발용)

장점:

• 코드 수정 → 즉시 반영
• 디버깅 쉬움

단점:

• 느림
• TypeScript 변환 실시간 (CPU 사용)

---

프로덕션 환경 (서버)

## 1. 빌드 (개발자가 한 번만 실행)
npm run build

## dist/ 생성:
## - TypeScript → JavaScript (한 번만)
## - 모든 파일 합치기
## - 압축

## 2. 서버 실행 (dist 제공)
cd ../..
uv run app.py

## FastAPI가 dist/ 폴더를 그대로 제공
## 결과: http://localhost:8000 (프로덕션용)

장점:

• 빠름 (이미 빌드됨)
• 파일 적음 (네트워크 빠름)

단점:

• 코드 수정 → 재빌드 필요

---

📊 크기 비교

소스 코드 (src/)

src/
├── components/ (50개 파일)
├── hooks/ (10개 파일)
├── lib/ (5개 파일)
└── ... (총 100개 파일)

총 크기: ~5MB (주석, 공백 포함)
로딩 시간: ~5초 (100번 HTTP 요청)

빌드 결과 (dist/)

dist/
└── assets/
    ├── index.abc123.js (500KB)
    └── index.def456.css (50KB)

총 크기: ~550KB (75% 압축)
로딩 시간: ~0.5초 (2번 HTTP 요청)

차이: 10배 빠름! 🚀

---

🤔 자주 묻는 질문

Q1: 그럼 GitHub에는 뭘 올려야 하나?

A: 소스 코드만 올립니다!

## ✅ GitHub에 올리기
git add src/
git add package.json
git add vite.config.ts

## ❌ dist는 제외
echo "dist/" >> .gitignore

이유:

• 다른 개발자가 npm run build로 dist를 만들 수 있음
• dist는 계속 바뀜 (파일명에 해시)
• Git 히스토리 커짐

---

Q2: 서버에서는 dist를 어떻게 만들어?

A: GitHub에서 clone 후 빌드

## 서버에서 실행
git clone https://github.com/you/cvlab-kit.git
cd cvlab-kit/web_helper/frontend

npm install  # package.json 보고 의존성 설치
npm run build  # dist/ 생성

cd ../..
uv run app.py  # dist/ 제공

또는 GitHub Actions로 자동화:

## .github/workflows/deploy.yml
- run: npm install
- run: npm run build
- run: deploy dist/ to server

---

Q3: 개발할 때는?

A: dist 필요 없음!

## 터미널 1: 백엔드
uv run app.py --dev

## 터미널 2: 프론트엔드 (소스 코드 직접 사용)
cd web_helper/frontend
npm run dev

--dev 모드에서는: - FastAPI: http://localhost:8000 (API만) - Vite: http://localhost:5173 (소스 코드 직접 실행)

---

Q4: 왜 파일명에 해시가 있어? (index.abc123.js)

A: 브라우저 캐싱 때문

문제:

<!-- 캐싱으로 옛날 버전 사용 -->
<script src="index.js"></script>

사용자 브라우저가 index.js를 캐싱하면, 업데이트해도 옛날 파일을 계속 사용!

해결:

<!-- 코드 바뀌면 파일명 바뀜 → 캐시 무효화 -->
<script src="index.abc123.js"></script>

코드 수정 → 빌드 → 해시 바뀜 (abc123 → def456) → 브라우저가 새 파일 다운로드 ✅

---

📖 정리

흐름 요약

1. 개발자가 소스 코드 작성 (src/)
   ↓
2. npm run build 실행
   ↓
3. dist/ 생성 (컴파일 + 번들 + 압축)
   ↓
4. 서버가 dist/ 제공
   ↓
5. 사용자 브라우저가 다운로드 & 실행

GitHub 워크플로우

1. 개발자: 소스 코드 작성 (src/)
   ↓
2. git add src/ && git commit && git push
   ↓
3. GitHub: 소스 코드 저장 (dist/ 제외)
   ↓
4. 서버: git clone
   ↓
5. 서버: npm install && npm run build
   ↓
6. 서버: dist/ 생성 & 제공

---

🎨 시각화

┌─────────────────────────────────────────────┐
│ 개발자                                       │
│                                             │
│  src/App.tsx (TypeScript, 읽기 쉬움)         │
│  src/Button.tsx                             │
│  src/utils.ts                               │
│  ... (100개 파일)                            │
└─────────────────────────────────────────────┘
                    ↓
            npm run build (빌드)
                    ↓
┌─────────────────────────────────────────────┐
│ dist/ (브라우저가 이해)                       │
│                                             │
│  index.html                                 │
│  assets/index.abc123.js (압축, 난독화)       │
│  assets/index.def456.css                    │
└─────────────────────────────────────────────┘
                    ↓
             서버가 제공
                    ↓
┌─────────────────────────────────────────────┐
│ 사용자 브라우저                               │
│                                             │
│  index.html 다운로드                         │
│  index.abc123.js 다운로드                    │
│  실행! ✅                                     │
└─────────────────────────────────────────────┘

---

이제 이해되셨나요?

핵심:

• 소스 코드 = 개발자용 (TypeScript, 읽기 쉬움, 파일 많음)
• dist = 사용자용 (JavaScript, 압축, 파일 적음)
• GitHub에는 소스 코드만 올림
• 서버에서 빌드해서 dist 생성