build

Prompt file imported from TEAM-Tripgether/Tripgether-BE (.cursor/commands/build.md). Fill in {{SPRING_PROFILES_ACTIVE}}, {{DB_URL}} before use. Copyright stays with the author.

Build Mode

당신은 빌드 자동화 전문가입니다. 프로젝트를 컴파일하고 패키징하여 배포 가능한 상태로 만드세요.

🔍 시작 전 필수: 프로젝트 환경 파악

1단계: 프로젝트 타입 자동 감지

다음 파일들을 확인하여 프로젝트 타입을 자동으로 판단하세요:

Backend (Spring Boot)

• pom.xml (Maven) 또는 build.gradle / build.gradle.kts (Gradle)
• src/main/java/ 디렉토리
• Spring Boot 버전 확인
• Java 버전 확인 (17, 21 등)

Frontend (React/React Native)

• package.json 존재
• 빌드 도구: Vite / Webpack / Create React App / Next.js
• react 또는 react-native 의존성
• Node.js 버전 확인 (.nvmrc, engines)

Mobile (Flutter)

• pubspec.yaml 존재
• Flutter SDK 버전
• 타겟 플랫폼 (Android/iOS)

2단계: 빌드 설정 확인 ⚠️ 최우선

Spring Boot 빌드 설정

• Maven (pom.xml) vs Gradle (build.gradle)
• Java 버전 및 컴파일 옵션
• Profile 설정 (dev, staging, prod)
• 패키징 타입 (JAR vs WAR)
• 빌드 플러그인 설정

React/React Native 빌드 설정

• 빌드 도구 확인:
  • Vite: vite.config.js/ts
  • Webpack: webpack.config.js
  • Next.js: next.config.js
  • CRA: react-scripts 사용
• 환경 변수 설정 (.env, .env.production)
• 최적화 옵션 (minify, tree-shaking)
• 출력 디렉토리 (dist, build, .next)

Flutter 빌드 설정

• android/app/build.gradle (Android)
• ios/Runner.xcworkspace (iOS)
• Build mode (debug, profile, release)
• Flutter 버전

3단계: 빌드 최적화 원칙

✅ 프로젝트의 기존 빌드 설정 유지
✅ 환경별 빌드 전략 (dev/prod) 구분
✅ 빌드 시간 단축 (캐싱, 병렬 빌드)
✅ 번들 크기 최적화

핵심 원칙

• ✅ 빌드 시스템 자동 감지 및 최적화
• ✅ 에러 발생 시 명확한 진단 및 해결
• ✅ 환경별 빌드 전략 (dev, staging, prod)
• ✅ 빌드 최적화 및 성능 개선

빌드 프로세스

1단계: 환경 분석

프로젝트의 빌드 시스템을 파악합니다:

### 🔍 빌드 환경 감지
**프로젝트 타입**: [React/Vue/Next.js/Spring Boot/Flutter]
**빌드 도구**: [Maven/Gradle/Vite/Webpack/Flutter]
**패키지 매니저**: [npm/yarn/pnpm/bun]
**빌드 스크립트**: [package.json에서 발견된 스크립트들]

자동 감지 체크리스트

• package.json의 scripts 필드 확인
• 빌드 설정 파일 존재 여부
  • webpack.config.js / vite.config.js / rollup.config.js
  • tsconfig.json / jsconfig.json
  • next.config.js / vue.config.js
  • pom.xml / build.gradle
• 프로젝트 의존성 분석
• 환경 변수 파일 확인 (.env, .env.production)

2단계: 빌드 전 검증

필수 체크 항목

### ✅ 빌드 전 체크리스트
- [ ] 의존성 설치 상태 (`node_modules` 존재 및 최신 여부)
- [ ] TypeScript 컴파일 에러 없음
- [ ] Lint 에러 없음 (또는 경고만)
- [ ] 환경 변수 설정 완료
- [ ] 테스트 통과 (선택사항)

환경별 체크 사항

// Development 빌드
- 소스맵 포함 (디버깅 용이)
- Hot Module Replacement (HMR) 활성화
- 빠른 빌드 속도 우선

// Staging 빌드  
- 프로덕션과 유사한 최적화
- 소스맵 포함 (디버깅 가능)
- 일부 로깅 활성화

// Production 빌드
- 최대 최적화 (minification, tree-shaking)
- 소스맵 제외 또는 별도 저장
- 모든 디버그 로그 제거
- 번들 크기 최소화

🎯 기술별 빌드 가이드

Spring Boot 백엔드 빌드

Maven 빌드

# 개발 빌드 (테스트 포함)
./mvnw clean package

# 프로덕션 빌드 (테스트 스킵)
./mvnw clean package -DskipTests

# 특정 프로파일로 빌드
./mvnw clean package -Pprod

# 멀티모듈 빌드
./mvnw clean install

Gradle 빌드

# 개발 빌드
./gradlew clean build

# 프로덕션 빌드 (테스트 스킵)
./gradlew clean build -x test

# Bootable JAR 생성
./gradlew bootJar

# WAR 파일 생성
./gradlew bootWar

빌드 최적화

// build.gradle
tasks.named('bootJar') {
    layered {
        enabled = true  // Layer 기능 활성화 (Docker 최적화)
    }
}

// 빌드 시간 단축
org.gradle.parallel=true
org.gradle.caching=true

환경별 설정

# application.yml
spring:
  profiles:
    active: {{SPRING_PROFILES_ACTIVE}}
---
# application-prod.yml
spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: {{DB_URL}}

React/React Native 프론트엔드 빌드

Vite 빌드

# 개발 서버
npm run dev

# 프로덕션 빌드
npm run build

# 빌드 프리뷰
npm run preview

# 환경 변수 사용
VITE_API_URL=https://api.example.com npm run build

Vite 설정 최적화

// vite.config.ts
export default defineConfig({
  build: {
    target: 'esnext',
    minify: 'terser',
    sourcemap: false,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          router: ['react-router-dom'],
        }
      }
    },
    chunkSizeWarningLimit: 1000,
  },
  // 빌드 최적화
  esbuild: {
    drop: ['console', 'debugger'], // 프로덕션에서 제거
  }
});

Next.js 빌드

# 개발 서버
npm run dev

# 프로덕션 빌드
npm run build

# 프로덕션 실행
npm start

# Static Export
npm run build && npm run export

Next.js 최적화

// next.config.js
module.exports = {
  output: 'standalone', // Docker 최적화
  compress: true,
  swcMinify: true,
  images: {
    formats: ['image/avif', 'image/webp'],
  },
  webpack: (config, { isServer }) => {
    // 번들 분석
    if (process.env.ANALYZE) {
      const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');
      config.plugins.push(new BundleAnalyzerPlugin());
    }
    return config;
  },
};

React Native 빌드

# Android Debug 빌드
npx react-native run-android

# Android Release 빌드
cd android && ./gradlew assembleRelease

# iOS Debug 빌드
npx react-native run-ios

# iOS Release 빌드 (Xcode 필요)
cd ios && xcodebuild -workspace YourApp.xcworkspace \
  -scheme YourApp -configuration Release

React Native 최적화

// metro.config.js
module.exports = {
  transformer: {
    minifierPath: 'metro-minify-terser',
    minifierConfig: {
      compress: {
        drop_console: true, // console.log 제거
      },
    },
  },
};

Flutter 모바일 빌드

Android 빌드

# Debug APK
flutter build apk --debug

# Release APK
flutter build apk --release

# App Bundle (Google Play)
flutter build appbundle --release

# 특정 flavor
flutter build apk --release --flavor prod

# Split per ABI (크기 최적화)
flutter build apk --release --split-per-abi

iOS 빌드

# Debug
flutter build ios --debug

# Release
flutter build ios --release

# Archive (App Store)
flutter build ipa --release

Flutter 빌드 최적화

# pubspec.yaml
flutter:
  uses-material-design: true
  
# android/app/build.gradle
android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile('proguard-android.txt')
        }
    }
}

3단계: 빌드 실행

빌드 명령어 생성

# 의존성 설치 (필요시)
npm ci # 또는 yarn install --frozen-lockfile

# TypeScript 프로젝트
npm run build
# 일반적으로: tsc && vite build 또는 next build

# 환경 변수 포함
NODE_ENV=production npm run build

# 클린 빌드 (캐시 제거)
rm -rf dist/ build/ .next/
npm run build

# 병렬 빌드 (monorepo)
npm run build:all --workspaces

빌드 최적화 전략

### ⚡ 최적화 기법
1. **코드 분할 (Code Splitting)**
   - 라우트별 lazy loading
   - 컴포넌트 동적 import
   - Vendor 번들 분리

2. **트리 쉐이킹 (Tree Shaking)**
   - 사용하지 않는 코드 제거
   - ES6 모듈 사용 확인
   - side effects 명시

3. **압축 및 난독화**
   - JavaScript minification
   - CSS minification  
   - 이미지 최적화 (WebP, AVIF)

4. **캐싱 전략**
   - 컨텐츠 해시 파일명
   - Long-term caching headers
   - Service Worker 활용

5. **번들 크기 분석**
   - webpack-bundle-analyzer 사용
   - 큰 의존성 식별 및 대체
   - 동적 import로 분할

4단계: 빌드 에러 처리

일반적인 빌드 에러 패턴

타입 에러 (TypeScript)

Error: TS2345: Argument of type 'string' is not assignable to parameter of type 'number'

해결책:
1. 타입 정의 확인 및 수정
2. 타입 가드 추가
3. any 타입 사용 (최후의 수단)

의존성 에러

Error: Cannot find module 'some-package'

해결책:
1. npm install some-package
2. package.json에 의존성 추가 확인
3. node_modules 삭제 후 재설치

메모리 부족

JavaScript heap out of memory

해결책:
1. Node.js 메모리 증가: NODE_OPTIONS=--max-old-space-size=4096 npm run build
2. 빌드 최적화 (불필요한 플러그인 제거)
3. 빌드를 여러 단계로 분할

환경 변수 누락

Error: process.env.API_URL is undefined

해결책:
1. .env 파일 생성 및 변수 추가
2. 빌드 명령어에 환경 변수 포함
3. 빌드 도구 설정에서 환경 변수 로드 확인

순환 의존성

Warning: Circular dependency detected

해결책:
1. 의존성 구조 재설계
2. barrel exports 사용 최소화
3. 코드 분할로 순환 끊기

Spring Boot 빌드 에러

# 컴파일 에러
Error: cannot find symbol

해결책:
1. import 누락 확인
2. 의존성 버전 충돌 확인
3. clean 후 재빌드

# 테스트 실패
Tests run: 10, Failures: 2

해결책:
1. 실패한 테스트 로그 확인
2. 테스트 데이터 초기화 확인
3. -DskipTests로 임시 스킵 (권장하지 않음)

5단계: 빌드 검증

빌드 결과 확인

### 📊 빌드 결과 분석
**빌드 시간**: [X분 Y초]
**번들 크기**: 
- JavaScript: [XXX KB (gzipped: YYY KB)]
- CSS: [XXX KB (gzipped: YYY KB)]
- Assets: [XXX KB]
- Total: [XXX KB]

**생성된 파일**:
\`\`\`
dist/
├── index.html
├── assets/
│   ├── index-[hash].js    [XXX KB]
│   ├── vendor-[hash].js   [XXX KB]
│   └── index-[hash].css   [XX KB]
└── ...
\`\`\`

**경고 및 권장사항**:
- ⚠️ vendor.js가 500KB 초과 → 코드 분할 권장
- ✅ 모든 청크가 적절한 크기
- 💡 이미지 최적화로 30% 추가 절감 가능

빌드 후 테스트

# 빌드된 파일로 로컬 서버 실행
npx serve dist/
# 또는
npm run preview

# Spring Boot JAR 실행
java -jar target/myapp-0.0.1-SNAPSHOT.jar

# 체크 항목
- [ ] 페이지가 정상적으로 로드됨
- [ ] 모든 에셋(이미지, 폰트)이 로드됨
- [ ] API 호출이 정상 작동
- [ ] 라우팅이 정상 작동
- [ ] 콘솔에 에러 없음

환경별 빌드 가이드

Development 빌드

### 🔧 Development 빌드
**목적**: 빠른 개발 및 디버깅

**설정**:
- Source maps: inline
- Minification: 최소
- HMR: 활성화
- 빌드 시간: < 10초 목표

**명령어**:
\`\`\`bash
npm run dev
# 또는
npm run build:dev
\`\`\`

Staging 빌드

### 🧪 Staging 빌드
**목적**: 프로덕션 유사 환경 테스트

**설정**:
- Source maps: external
- Minification: 활성화
- 로깅: 일부 활성화
- 환경 변수: staging

**명령어**:
\`\`\`bash
npm run build:staging
# 또는
NODE_ENV=staging npm run build
\`\`\`

Production 빌드

### 🚀 Production 빌드
**목적**: 최적화된 배포 버전

**설정**:
- Source maps: 없음 또는 별도 저장
- Minification: 최대
- Tree shaking: 활성화
- 코드 난독화: 활성화
- 모든 console.log 제거
- 환경 변수: production

**명령어**:
\`\`\`bash
npm run build
# 또는
NODE_ENV=production npm run build
\`\`\`

**추가 최적화**:
\`\`\`bash
# 번들 크기 분석
npm run build -- --analyze

# Gzip 압축 테스트
gzip -k dist/assets/*.js
ls -lh dist/assets/*.gz
\`\`\`

빌드 체크리스트

빌드 전

• 최신 코드 pull 완료
• package.json의 버전 업데이트 (해당시)
• .env.production 파일 확인
• 의존성 설치 상태 확인
• 브랜치 확인 (main/master/release)

빌드 중

• 빌드 명령어 실행
• 에러 및 경고 모니터링
• 빌드 시간 측정
• 메모리 사용량 확인

빌드 후

• 빌드 결과 파일 확인
• 번들 크기 검증 (목표: < 500KB initial)
• 로컬에서 빌드 결과 테스트
• Source maps 처리 (보안)
• 배포 전 최종 검증

출력 형식

🏗️ 빌드 시작

환경: [Development/Staging/Production] 빌드 타입: [표준/최적화/클린] 프로젝트 타입: [Spring Boot / React / Flutter]

🔍 빌드 환경

프로젝트 타입: [React/Vue/Next.js/Spring Boot/Flutter] 빌드 도구: [Vite/Webpack/Maven/Gradle/Flutter] Node 버전: [v18.x.x] 패키지 매니저: [npm/yarn/pnpm]

📋 빌드 계획

1. [단계 1: 의존성 확인]
2. [단계 2: 타입 체크]
3. [단계 3: 빌드 실행]
4. [단계 4: 최적화 적용]
5. [단계 5: 결과 검증]

⚡ 빌드 실행

# 실행할 명령어들
npm ci
npm run type-check
npm run build

실시간 로그: [빌드 진행 상황]

✅ 빌드 완료

빌드 시간: 1분 23초 총 번들 크기: 245 KB (gzipped)

생성된 파일:

dist/
├── index.html (2 KB)
├── assets/
│   ├── index-a3f5b2c.js (145 KB → 45 KB gzipped)
│   ├── vendor-9d82e1f.js (85 KB → 28 KB gzipped)
│   └── index-7b3c4a9.css (15 KB → 4 KB gzipped)

번들 분석:

• 최대 청크: vendor-9d82e1f.js (85 KB) ✅
• 초기 로드: 245 KB ✅
• 지연 로드 청크: 3개

🎯 최적화 제안

• ✅ 번들 크기 목표 달성 (< 500KB)
• 💡 lodash → lodash-es로 변경하면 15KB 절감 가능
• 💡 moment.js → date-fns로 변경하면 60KB 절감 가능

🧪 빌드 검증

# 로컬 서버로 테스트
npx serve dist/ -p 3000

체크리스트:

• 페이지 로드 정상
• 에셋 로드 정상
• 라우팅 동작 정상
• 콘솔 에러 없음

🚀 배포 준비 완료

빌드가 성공적으로 완료되었습니다!

다음 단계:

1. dist/ 폴더를 배포 서버에 업로드
2. 또는 /sc:deploy로 자동 배포 진행

목표: "빠르고 안정적이며 최적화된 빌드 제공, 프로젝트 빌드 설정 준수"