@kood/claude-code 0.1.0

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

@@ -0,0 +1,346 @@
+# Cloudflare 배포
+
+> **상위 문서**: [배포](./index.md)
+
+Cloudflare는 Workers와 Pages 두 가지 배포 옵션을 제공합니다.
+
+## 배포 옵션 비교
+
+| 옵션 | Preset | 특징 |
+|------|--------|------|
+| **Workers** | `cloudflare_module` | 서버리스 컴퓨팅, KV/D1 통합 |
+| **Pages** | `cloudflare_pages` | 정적 사이트 + Functions |
+
+## Cloudflare Workers
+
+### 1. 패키지 설치
+
+```bash
+yarn add @cloudflare/vite-plugin wrangler -D
+```
+
+### 2. Vite 설정 (직접 통합)
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import { cloudflare } from '@cloudflare/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    cloudflare({ viteEnvironment: { name: 'ssr' } }),
+    tanstackStart(),
+    react(),
+  ],
+})
+```
+
+### 3. Wrangler 설정
+
+```jsonc
+// wrangler.jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-tanstack-app",
+  "compatibility_date": "2025-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "main": "@tanstack/react-start/server-entry"
+}
+```
+
+### 4. 배포
+
+```bash
+# 빌드
+yarn build
+
+# 배포
+wrangler deploy
+```
+
+## Cloudflare Pages
+
+### 1. Nitro 설정
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  preset: 'cloudflare_pages',
+  // Nitro v3 필수: Static Assets 지원을 위해 2024-09-19 이상 필요
+  compatibilityDate: '2024-09-19',
+  cloudflare: {
+    deployConfig: true,  // wrangler.json 자동 생성
+    nodeCompat: true,    // Node.js API 호환성
+  },
+})
+```
+
+### 2. Vite 설정 (Nitro 통합)
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import { nitro } from 'nitro/vite'
+
+export default defineConfig({
+  plugins: [
+    tanstackStart(),
+    nitro(),
+    react(),
+  ],
+})
+```
+
+### 3. 배포
+
+```bash
+# 빌드
+NITRO_PRESET=cloudflare_pages yarn build
+
+# Pages 배포
+wrangler pages deploy .output/public
+```
+
+## Wrangler 설정 상세
+
+### wrangler.toml (Workers)
+
+```toml
+name = "my-app"
+main = ".output/server/index.mjs"
+compatibility_date = "2025-01-01"
+compatibility_flags = ["nodejs_compat"]
+
+[vars]
+MY_VAR = "value"
+
+[[kv_namespaces]]
+binding = "MY_KV"
+id = "your-kv-id"
+
+[[d1_databases]]
+binding = "DB"
+database_name = "my-database"
+database_id = "your-database-id"
+```
+
+### wrangler.toml (Pages)
+
+```toml
+name = "my-pages-app"
+pages_build_output_dir = ".output/public"
+compatibility_date = "2025-01-01"
+compatibility_flags = ["nodejs_compat"]
+
+[[d1_databases]]
+binding = "DB"
+database_name = "my-database"
+database_id = "your-database-id"
+```
+
+## KV 스토리지 사용
+
+### KV 네임스페이스 생성
+
+```bash
+# KV 네임스페이스 생성
+wrangler kv:namespace create "MY_KV"
+
+# wrangler.toml에 바인딩 추가
+```
+
+### 코드에서 사용
+
+```typescript
+// server/api/kv-example.ts
+import { defineHandler } from 'nitro/h3'
+
+export default defineHandler(async (event) => {
+  const env = event.context.cloudflare.env
+
+  // KV 읽기
+  const value = await env.MY_KV.get('key')
+
+  // KV 쓰기
+  await env.MY_KV.put('key', 'value')
+
+  return { value }
+})
+```
+
+## D1 데이터베이스 사용
+
+### D1 데이터베이스 생성
+
+```bash
+# 데이터베이스 생성
+wrangler d1 create my-database
+
+# 마이그레이션 실행
+wrangler d1 migrations apply my-database
+```
+
+### 코드에서 사용
+
+```typescript
+// server/api/d1-example.ts
+import { defineHandler } from 'nitro/h3'
+
+export default defineHandler(async (event) => {
+  const env = event.context.cloudflare.env
+
+  // 쿼리 실행
+  const results = await env.DB.prepare(
+    'SELECT * FROM users WHERE id = ?'
+  ).bind(1).all()
+
+  return results
+})
+```
+
+## 환경변수 관리
+
+### 로컬 개발
+
+```bash
+# .dev.vars 파일 생성
+DATABASE_URL=your-local-url
+API_SECRET=your-secret
+```
+
+### 프로덕션
+
+```bash
+# 시크릿 설정
+wrangler secret put API_SECRET
+
+# 일반 변수 (wrangler.toml)
+[vars]
+NODE_ENV = "production"
+```
+
+## 커스텀 도메인
+
+### Pages
+
+```bash
+# 커스텀 도메인 추가
+wrangler pages project add-custom-domain my-app example.com
+```
+
+### Workers
+
+Cloudflare 대시보드에서 설정하거나:
+
+```toml
+# wrangler.toml
+routes = [
+  { pattern = "example.com/*", zone_name = "example.com" }
+]
+```
+
+## 개발 서버
+
+```bash
+# 로컬 개발 (Workers)
+wrangler dev
+
+# Pages 로컬 개발
+wrangler pages dev .output/public
+
+# 미니플레어 사용
+wrangler dev --local
+```
+
+## 트러블슈팅
+
+### Node.js API 호환성
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  preset: 'cloudflare_pages',
+  compatibilityDate: '2024-09-19',
+  cloudflare: {
+    nodeCompat: true,
+  },
+  // 또는 특정 폴리필 설정
+  unenv: {
+    alias: {
+      'node:buffer': 'buffer',
+    },
+  },
+})
+```
+
+### 번들 크기 최적화
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  preset: 'cloudflare_pages',
+  compatibilityDate: '2024-09-19',
+  // 외부화할 패키지
+  externals: ['@prisma/client'],
+  // 트리 쉐이킹
+  minify: true,
+})
+```
+
+### 로그 확인
+
+```bash
+# 실시간 로그
+wrangler tail
+
+# 특정 배포 로그
+wrangler tail --deployment-id [id]
+```
+
+## CI/CD 설정
+
+### GitHub Actions
+
+```yaml
+name: Deploy to Cloudflare
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - run: yarn install
+      - run: yarn build
+        env:
+          NITRO_PRESET: cloudflare_pages
+
+      - uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          command: pages deploy .output/public --project-name=my-app
+```
+
+## 참고 자료
+
+- [Cloudflare Workers 문서](https://developers.cloudflare.com/workers/)
+- [Cloudflare Pages 문서](https://developers.cloudflare.com/pages/)
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
+- [Nitro Cloudflare Preset](https://nitro.build/deploy/providers/cloudflare)

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

@@ -0,0 +1,102 @@
+# 배포 (Deployment)
+
+> **Framework**: TanStack Start + Nitro
+> **Source**: [Nitro Deployment](https://nitro.build/deploy), [TanStack Start Hosting](https://tanstack.com/start/latest/docs/framework/react/hosting)
+
+TanStack Start는 Nitro를 배포 레이어로 사용하여 다양한 플랫폼에 배포할 수 있습니다.
+
+## 문서 구조
+
+- [Nitro 설정](./nitro.md) - Nitro 배포 레이어 기본 설정
+- [Vercel](./vercel.md) - Vercel 배포 가이드
+- [Cloudflare](./cloudflare.md) - Cloudflare Workers/Pages 배포
+- [Railway](./railway.md) - Railway 배포 가이드
+
+## 배포 옵션 비교
+
+| 플랫폼 | Preset | Edge 지원 | 특징 |
+|--------|--------|-----------|------|
+| Vercel | `vercel` | ✅ | ISR, 자동 배포, Bun 런타임 |
+| Cloudflare Pages | `cloudflare_pages` | ✅ | 글로벌 CDN, Workers 통합 |
+| Cloudflare Workers | `cloudflare_module` | ✅ | 서버리스 컴퓨팅, KV 스토리지 |
+| Railway | `node-server` | ❌ | Docker 지원, 간편한 설정 |
+
+## 빠른 시작
+
+### 1. Nitro 플러그인 설치
+
+```bash
+yarn add nitro
+```
+
+### 2. Vite 설정
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import { nitro } from 'nitro/vite'
+
+export default defineConfig({
+  plugins: [
+    tanstackStart(),
+    nitro(),
+    react(),
+  ],
+})
+```
+
+### 3. Nitro 설정
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  preset: 'vercel', // 또는 cloudflare_pages, node-server 등
+  // Nitro v3 필수: Cloudflare Static Assets 지원을 위해 2024-09-19 이상 필요
+  compatibilityDate: '2024-09-19',
+})
+```
+
+### 4. 빌드 및 배포
+
+```bash
+# 빌드
+yarn build
+
+# 또는 환경변수로 preset 지정
+NITRO_PRESET=vercel yarn build
+```
+
+## Preset 선택 가이드
+
+### Edge 런타임이 필요한 경우
+- **Vercel**: `vercel` (Edge Functions 자동 지원)
+- **Cloudflare**: `cloudflare_pages` 또는 `cloudflare_module`
+
+### Node.js 서버가 필요한 경우
+- **Railway**: `node-server`
+- **기타 Node.js 호스팅**: `node-server`
+
+### 정적 사이트 생성 (SSG)
+- **정적 호스팅**: `static`
+
+## 환경변수
+
+모든 플랫폼에서 공통으로 사용하는 환경변수:
+
+```bash
+# 빌드 시 preset 지정
+NITRO_PRESET=vercel
+
+# 런타임 환경변수
+DATABASE_URL=postgresql://...
+API_SECRET=your-secret-key
+```
+
+## 참고 자료
+
+- [Nitro 공식 문서](https://nitro.build)
+- [TanStack Start Hosting](https://tanstack.com/start/latest/docs/framework/react/hosting)

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

@@ -0,0 +1,211 @@
+# Nitro 배포 레이어
+
+> **상위 문서**: [배포](./index.md)
+
+Nitro는 TanStack Start의 배포 레이어로, 다양한 플랫폼에 대한 preset을 제공합니다.
+
+## 설치
+
+```bash
+yarn add nitro
+```
+
+## Vite 통합
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import { nitro } from 'nitro/vite'
+
+export default defineConfig({
+  plugins: [
+    tanstackStart(),
+    nitro(),
+    react(),
+  ],
+})
+```
+
+## Nitro 설정
+
+### nitro.config.ts
+
+```typescript
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  // 배포 플랫폼 preset
+  preset: 'vercel',
+
+  // 호환성 설정 (Nitro v3 필수)
+  compatibilityDate: '2024-09-19',
+})
+```
+
+### 환경변수로 Preset 지정
+
+```bash
+# 빌드 시 환경변수로 지정
+NITRO_PRESET=cloudflare_pages yarn build
+
+# 또는 CLI 옵션
+nitro build --preset cloudflare_pages
+```
+
+## 주요 Preset 목록
+
+### 서버리스/Edge
+
+| Preset | 플랫폼 | 설명 |
+|--------|--------|------|
+| `vercel` | Vercel | Vercel Functions |
+| `cloudflare_pages` | Cloudflare | Pages Functions |
+| `cloudflare_module` | Cloudflare | Workers Module |
+| `netlify` | Netlify | Netlify Functions |
+| `aws_lambda` | AWS | Lambda Functions |
+
+### Node.js 서버
+
+| Preset | 플랫폼 | 설명 |
+|--------|--------|------|
+| `node-server` | 범용 | Node.js HTTP 서버 |
+| `node-cluster` | 범용 | 클러스터 모드 |
+| `bun` | Bun | Bun 런타임 |
+| `deno_deploy` | Deno | Deno Deploy |
+
+### 정적/기타
+
+| Preset | 플랫폼 | 설명 |
+|--------|--------|------|
+| `static` | 범용 | 정적 사이트 생성 |
+| `github_pages` | GitHub | GitHub Pages |
+| `render_com` | Render | Render.com |
+
+## 출력 구조
+
+빌드 후 `.output/` 디렉토리에 생성되는 파일:
+
+```
+.output/
+├── server/
+│   └── index.mjs      # 서버 엔트리포인트
+├── public/
+│   └── ...            # 정적 파일
+└── nitro.json         # Nitro 설정
+```
+
+## 런타임 설정
+
+### Node.js 호환성
+
+```typescript
+// nitro.config.ts
+export default defineNitroConfig({
+  preset: 'cloudflare_pages',
+  cloudflare: {
+    nodeCompat: true,  // Node.js API 호환성
+  },
+})
+```
+
+### 외부 패키지 처리
+
+```typescript
+// nitro.config.ts
+export default defineNitroConfig({
+  // 번들에서 제외할 패키지
+  externals: ['pg', 'mysql2'],
+
+  // 번들에 포함할 패키지
+  inlineDependencies: ['my-esm-package'],
+})
+```
+
+## 라우트 규칙
+
+```typescript
+// nitro.config.ts
+export default defineNitroConfig({
+  routeRules: {
+    // 정적 페이지 캐싱
+    '/': { prerender: true },
+
+    // ISR (Incremental Static Regeneration)
+    '/products/**': {
+      isr: {
+        expiration: 60, // 60초
+      },
+    },
+
+    // API 라우트 설정
+    '/api/**': {
+      cors: true,
+      headers: {
+        'Access-Control-Allow-Origin': '*',
+      },
+    },
+  },
+})
+```
+
+## 환경변수 관리
+
+### .env 파일
+
+```bash
+# .env.production
+DATABASE_URL=postgresql://...
+API_SECRET=your-secret-key
+```
+
+### 런타임에서 사용
+
+```typescript
+// server/api/example.ts
+import { defineHandler } from 'nitro/h3'
+
+export default defineHandler(() => {
+  const dbUrl = process.env.DATABASE_URL
+  // ...
+})
+```
+
+## 빌드 명령어
+
+```bash
+# 개발 서버
+yarn dev
+
+# 프로덕션 빌드
+yarn build
+
+# 빌드 결과 미리보기
+yarn preview
+
+# 특정 preset으로 빌드
+NITRO_PRESET=vercel yarn build
+```
+
+## 디버깅
+
+### 빌드 로그 확인
+
+```bash
+# 상세 로그 출력
+DEBUG=nitro:* yarn build
+```
+
+### 출력 검사
+
+```bash
+# 빌드 후 출력 확인
+ls -la .output/server/
+cat .output/nitro.json
+```
+
+## 참고 자료
+
+- [Nitro 공식 문서](https://nitro.build)
+- [Nitro Preset 목록](https://nitro.build/deploy)