@kood/claude-code 0.1.2 → 0.1.3

package/templates/tanstack-start/docs/deployment/vercel.md

@@ -1,12 +1,13 @@
 # Vercel 배포
 
 > **상위 문서**: [배포](./index.md)
+> **Version**: Nitro 3.x
 
-Vercel은 TanStack Start 앱을 위한 최적화된 배포 플랫폼입니다.
+Vercel은 TanStack Start 앱을 위한 최적화된 서버리스 배포 플랫폼입니다.
 
-## 빠른 시작
+---
 
-### 1. Nitro 설정
+## 🚀 Quick Reference (복사용)
 
 ```typescript
 // nitro.config.ts
@@ -14,47 +15,210 @@ import { defineNitroConfig } from 'nitro/config'
 
 export default defineNitroConfig({
   preset: 'vercel',
+  compatibilityDate: '2024-09-19',
 })
 ```
 
-### 2. 빌드 및 배포
+```json
+// vercel.json
+{
+  "buildCommand": "pnpm build",
+  "outputDirectory": ".vercel/output"
+}
+```
 
 ```bash
-# 빌드
-yarn build
-
-# Vercel CLI로 배포
+# Vercel CLI 배포
+vercel login
 vercel
 ```
 
-## Vercel 설정
+---
 
-### vercel.json
+## Nitro 설정
+
+### 기본 설정
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  // Vercel 서버리스 preset
+  preset: 'vercel',
+
+  // 호환성 날짜 (Nitro v3 필수)
+  compatibilityDate: '2024-09-19',
+})
+```
+
+### Edge Functions 설정
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  // Vercel Edge Functions preset
+  preset: 'vercel-edge',
+
+  // 호환성 날짜
+  compatibilityDate: '2024-09-19',
+})
+```
+
+### Bun 런타임 설정
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  preset: 'vercel',
+  compatibilityDate: '2024-09-19',
+
+  // Bun 런타임 사용
+  vercel: {
+    functions: {
+      runtime: 'bun@1',
+    },
+  },
+})
+```
+
+---
+
+## Vite 설정
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import { nitro } from 'nitro/vite'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [
+    tanstackStart(),
+    nitro(),
+    viteReact(),
+  ],
+})
+```
+
+---
+
+## vercel.json 설정
+
+### 기본 설정
+
+```json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "buildCommand": "pnpm build",
+  "outputDirectory": ".vercel/output",
+  "framework": null,
+  "installCommand": "pnpm install"
+}
+```
+
+### 고급 설정
 
 ```json
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
-  "buildCommand": "yarn build",
-  "outputDirectory": ".output",
-  "framework": null
+  "buildCommand": "pnpm build",
+  "outputDirectory": ".vercel/output",
+
+  "functions": {
+    "api/**/*.ts": {
+      "memory": 1024,
+      "maxDuration": 30
+    }
+  },
+
+  "headers": [
+    {
+      "source": "/api/(.*)",
+      "headers": [
+        { "key": "Access-Control-Allow-Origin", "value": "*" },
+        { "key": "Access-Control-Allow-Methods", "value": "GET, POST, PUT, DELETE, OPTIONS" }
+      ]
+    }
+  ],
+
+  "rewrites": [
+    { "source": "/(.*)", "destination": "/api" }
+  ]
 }
 ```
 
-### 환경변수
+---
+
+## 배포 방법
+
+### 방법 1: GitHub 연동 (권장)
 
-Vercel 대시보드에서 설정하거나 CLI 사용:
+1. **Vercel 프로젝트 생성**
+   - [Vercel 대시보드](https://vercel.com) 접속
+   - "Add New" → "Project" → GitHub 저장소 선택
+
+2. **빌드 설정**
+   - Framework Preset: "Other"
+   - Build Command: `pnpm build`
+   - Output Directory: `.vercel/output`
+   - Install Command: `pnpm install`
+
+3. **환경 변수 설정**
+   - Vercel 대시보드에서 Settings → Environment Variables
+
+### 방법 2: Vercel CLI
 
 ```bash
-# 환경변수 추가
-vercel env add DATABASE_URL
+# Vercel CLI 설치
+npm install -g vercel
 
-# 환경변수 확인
-vercel env ls
+# 로그인
+vercel login
+
+# 프로젝트 연결 및 배포
+vercel
+
+# 프로덕션 배포
+vercel --prod
+
+# 환경 변수 설정
+vercel env add DATABASE_URL
+vercel env add API_SECRET
 ```
 
+---
+
 ## ISR (Incremental Static Regeneration)
 
-### 기본 ISR 설정
+### ISR 설정
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  preset: 'vercel',
+  compatibilityDate: '2024-09-19',
+
+  // ISR 설정
+  vercel: {
+    config: {
+      // 정적 페이지 재생성 간격 (초)
+      isr: {
+        bypassToken: process.env.ISR_BYPASS_TOKEN,
+      },
+    },
+  },
+})
+```
+
+### 라우트별 ISR
 
 ```typescript
 // nitro.config.ts
@@ -62,6 +226,8 @@ import { defineNitroConfig } from 'nitro/config'
 
 export default defineNitroConfig({
   preset: 'vercel',
+  compatibilityDate: '2024-09-19',
+
   routeRules: {
     // 60초마다 재검증
     '/products/**': {
@@ -69,6 +235,11 @@ export default defineNitroConfig({
         expiration: 60,
       },
     },
+
+    // 캐시하지 않음
+    '/api/user/**': {
+      isr: false,
+    },
   },
 })
 ```
@@ -81,6 +252,8 @@ import { defineNitroConfig } from 'nitro/config'
 
 export default defineNitroConfig({
   preset: 'vercel',
+  compatibilityDate: '2024-09-19',
+
   vercel: {
     config: {
       bypassToken: process.env.VERCEL_BYPASS_TOKEN,
@@ -120,52 +293,36 @@ export default defineHandler(async (event) => {
 })
 ```
 
-## Bun 런타임
+---
 
-### nitro.config.ts 설정
+## 환경변수
 
-```typescript
-import { defineNitroConfig } from 'nitro/config'
+### Vercel 대시보드에서 설정
 
-export default defineNitroConfig({
-  preset: 'vercel',
-  vercel: {
-    functions: {
-      runtime: 'bun1.x',
-    },
-  },
-})
 ```
-
-### vercel.json 설정
-
-```json
-{
-  "$schema": "https://openapi.vercel.sh/vercel.json",
-  "bunVersion": "1.x"
-}
+DATABASE_URL=postgresql://user:pass@host:5432/db
+API_SECRET=your-secret-key
+NODE_ENV=production
 ```
 
-## Edge Functions
+### 환경별 설정
 
-### Edge 런타임 설정
+Vercel은 환경별로 다른 값 설정 가능:
+- **Production**: 프로덕션 환경
+- **Preview**: PR 프리뷰 환경
+- **Development**: 로컬 개발 환경
 
-```typescript
-// nitro.config.ts
-import { defineNitroConfig } from 'nitro/config'
+### Vercel 자동 제공 변수
 
-export default defineNitroConfig({
-  preset: 'vercel',
-  routeRules: {
-    '/api/edge/**': {
-      // Edge 런타임에서 실행
-      headers: {
-        'x-vercel-edge': '1',
-      },
-    },
-  },
-})
-```
+| 변수 | 설명 |
+|------|------|
+| `VERCEL` | Vercel 환경인지 여부 ("1") |
+| `VERCEL_ENV` | 환경 (production, preview, development) |
+| `VERCEL_URL` | 배포 URL |
+| `VERCEL_REGION` | 실행 리전 |
+| `VERCEL_GIT_COMMIT_SHA` | Git 커밋 SHA |
+
+---
 
 ## 환경별 설정
 
@@ -179,6 +336,8 @@ const isProduction = process.env.VERCEL_ENV === 'production'
 
 export default defineNitroConfig({
   preset: 'vercel',
+  compatibilityDate: '2024-09-19',
+
   routeRules: {
     '/api/**': {
       cors: !isProduction,  // 개발 환경에서만 CORS 허용
@@ -187,6 +346,8 @@ export default defineNitroConfig({
 })
 ```
 
+---
+
 ## 모노레포 설정
 
 ### vercel.json
@@ -194,12 +355,14 @@ export default defineNitroConfig({
 ```json
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
-  "installCommand": "yarn install",
-  "buildCommand": "yarn workspace web build",
-  "outputDirectory": "apps/web/.output"
+  "installCommand": "pnpm install",
+  "buildCommand": "pnpm --filter web build",
+  "outputDirectory": "apps/web/.vercel/output"
 }
 ```
 
+---
+
 ## GitHub 통합
 
 ### 자동 배포 설정
@@ -224,46 +387,140 @@ export default defineNitroConfig({
 }
 ```
 
-## 도메인 설정
+---
 
-```bash
-# 커스텀 도메인 추가
-vercel domains add example.com
+## CI/CD 설정
 
-# DNS 설정 확인
-vercel domains inspect example.com
+### GitHub Actions
+
+```yaml
+# .github/workflows/vercel.yml
+name: Deploy to Vercel
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build
+        run: pnpm build
+
+      - name: Deploy to Vercel
+        uses: amondnet/vercel-action@v25
+        with:
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+          vercel-args: ${{ github.ref == 'refs/heads/main' && '--prod' || '' }}
 ```
 
-## 트러블슈팅
+---
 
-### 빌드 실패
+## 최적화
 
-```bash
-# 로컬에서 Vercel 빌드 시뮬레이션
-vercel build
+### Cold Start 최소화
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  preset: 'vercel',
+  compatibilityDate: '2024-09-19',
+
+  // 번들 최적화
+  minify: true,
 
-# 상세 로그 확인
-vercel logs [deployment-url]
+  // 트리 쉐이킹
+  experimental: {
+    wasm: true,
+  },
+})
 ```
 
-### Function 크기 초과
+### Function 크기 최소화
 
 ```typescript
 // nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
 export default defineNitroConfig({
   preset: 'vercel',
-  // 외부 패키지로 분리
-  externals: ['@prisma/client', 'sharp'],
+  compatibilityDate: '2024-09-19',
+
+  // 외부 패키지 제외 (번들 크기 감소)
+  externals: ['sharp', 'prisma', '@prisma/client'],
 })
 ```
 
-### 환경변수 누락
+---
+
+## 도메인 설정
 
 ```bash
-# 환경변수 풀 다운
+# 커스텀 도메인 추가
+vercel domains add example.com
+
+# DNS 설정 확인
+vercel domains inspect example.com
+```
+
+---
+
+## 트러블슈팅
+
+### 일반적인 문제
+
+| 문제 | 원인 | 해결 |
+|------|------|------|
+| Function Timeout | 실행 시간 초과 | `maxDuration` 증가 또는 최적화 |
+| Edge 호환성 오류 | Node.js API 사용 | Edge 호환 API로 변경 |
+| 환경 변수 누락 | 설정 안됨 | Vercel 대시보드에서 설정 |
+| 빌드 실패 | 의존성 문제 | `pnpm-lock.yaml` 확인 |
+
+### 디버깅
+
+```bash
+# 로컬에서 Vercel 환경 시뮬레이션
+vercel dev
+
+# 로그 확인
+vercel logs
+
+# 환경 변수 확인
+vercel env ls
+
+# 환경 변수 풀 다운
 vercel env pull .env.local
+
+# 함수 상태 확인
+vercel inspect
 ```
 
+---
+
 ## 유용한 명령어
 
 ```bash
@@ -280,8 +537,26 @@ vercel ls
 vercel rollback [deployment-url]
 ```
 
+---
+
+## package.json 스크립트
+
+```json
+{
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && tsc --noEmit",
+    "start": "node .output/server/index.mjs",
+    "preview": "vite preview"
+  }
+}
+```
+
+---
+
 ## 참고 자료
 
+- [TanStack Start Hosting](https://tanstack.com/start/latest/docs/framework/react/hosting)
 - [Vercel 공식 문서](https://vercel.com/docs)
 - [Vercel CLI](https://vercel.com/docs/cli)
 - [Nitro Vercel Preset](https://nitro.build/deploy/providers/vercel)

package/templates/tanstack-start/docs/git/{index.md → git.md}

@@ -14,6 +14,7 @@
 ❌ 커밋 메시지 여러 줄 작성
 ❌ 커밋 메시지에 이모지 사용
 ❌ 커밋 메시지에 마침표(.) 사용
+❌ 여러 작업을 하나의 커밋으로 퉁치기
 ```
 
 ---
@@ -23,10 +24,30 @@
 ### 작업 완료 후 반드시 실행
 
 ```bash
-git add .
+git add <관련 파일들>
 git commit -m "<prefix>: <설명>"
 ```
 
+### ⭐ 커밋 분리 원칙
+
+**하나의 커밋 = 하나의 논리적 변경 단위**
+
+```bash
+# ❌ 잘못된 방식: 모든 작업을 하나로 퉁침
+git add .
+git commit -m "feat: 여러 기능 추가"
+
+# ✅ 올바른 방식: 논리적 단위로 분리
+git add src/routes/auth.tsx src/functions/auth.ts
+git commit -m "feat: 사용자 로그인 기능 추가"
+
+git add src/routes/profile.tsx src/functions/user.ts
+git commit -m "feat: 프로필 조회 기능 추가"
+
+git add docs/
+git commit -m "docs: API 문서 업데이트"
+```
+
 ---
 
 ## 📝 커밋 형식
@@ -97,6 +118,9 @@ feat: 로그인 기능 추가
 
 - 이메일 인증 추가
 - 세션 관리 구현
+
+# 여러 작업을 하나로 퉁침 (금지)
+feat: 로그인, 회원가입, 프로필 기능 추가
 ```
 
 ---
@@ -107,19 +131,63 @@ feat: 로그인 기능 추가
 # 1. 작업 전 최신 코드 동기화
 git pull origin main
 
-# 2. 코드 작업 진행
-# ...
+# 2. 기능 A 작업 완료 → 커밋
+git add src/routes/feature-a.tsx src/functions/feature-a.ts
+git commit -m "feat: 기능 A 구현"
 
-# 3. 변경사항 커밋
-git add .
-git commit -m "feat: 새 기능 설명"
+# 3. 기능 B 작업 완료 → 커밋
+git add src/routes/feature-b.tsx src/functions/feature-b.ts
+git commit -m "feat: 기능 B 구현"
+
+# 4. 문서 작업 완료 → 커밋
+git add docs/
+git commit -m "docs: 기능 A, B 문서 추가"
 
-# 4. 푸시
+# 5. 푸시
 git push origin main
 ```
 
 ---
 
+## 📦 커밋 분리 가이드
+
+### 언제 커밋을 분리해야 하나요?
+
+| 상황 | 커밋 분리 |
+|------|----------|
+| 서로 다른 기능 구현 | ✅ 분리 |
+| 버그 수정 + 새 기능 | ✅ 분리 |
+| 코드 변경 + 문서 변경 | ✅ 분리 |
+| 리팩토링 + 기능 추가 | ✅ 분리 |
+| 동일 기능의 라우트 + 함수 | 🔄 묶어도 됨 |
+| 동일 기능의 스키마 + 서비스 | 🔄 묶어도 됨 |
+
+### 예시: 사용자 관리 기능 개발
+
+```bash
+# 1. 인증 기능 커밋
+git add src/routes/auth/ src/functions/auth.ts src/middleware/auth.ts
+git commit -m "feat: 사용자 인증 기능 추가"
+
+# 2. 프로필 기능 커밋
+git add src/routes/profile/ src/functions/user.ts
+git commit -m "feat: 프로필 조회 및 수정 기능 추가"
+
+# 3. 유효성 검사 커밋
+git add src/validators/
+git commit -m "feat: 사용자 입력 유효성 검사 추가"
+
+# 4. 테스트 커밋
+git add tests/
+git commit -m "test: 사용자 관리 기능 테스트 추가"
+
+# 5. 문서 커밋
+git add docs/
+git commit -m "docs: 사용자 API 문서 추가"
+```
+
+---
+
 ## 🌿 브랜치 전략
 
 ### 간단한 프로젝트
@@ -166,6 +234,12 @@ git restore --staged .
 # 변경사항 임시 저장
 git stash
 git stash pop
+
+# 특정 파일만 스테이징
+git add <파일경로>
+
+# 대화형 스테이징 (부분 커밋용)
+git add -p
 ```
 
 ---