@kood/claude-code 0.1.2 → 0.1.3

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

@@ -1,38 +1,82 @@
 # Cloudflare 배포
 
 > **상위 문서**: [배포](./index.md)
+> **Source**: [TanStack Start Hosting](https://tanstack.com/start/latest/docs/framework/react/hosting)
 
 Cloudflare는 Workers와 Pages 두 가지 배포 옵션을 제공합니다.
 
+---
+
+## 🚀 Quick Reference (복사용)
+
+### Workers 직접 통합 (권장)
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import { cloudflare } from '@cloudflare/vite-plugin'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [
+    cloudflare({ viteEnvironment: { name: 'ssr' } }),
+    tanstackStart(),
+    viteReact(),
+  ],
+})
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-tanstack-app",
+  "compatibility_date": "2024-09-19",
+  "compatibility_flags": ["nodejs_compat"],
+  "main": "@tanstack/react-start/server-entry"
+}
+```
+
+```bash
+pnpm build && wrangler deploy
+```
+
+---
+
 ## 배포 옵션 비교
 
-| 옵션 | Preset | 특징 |
-|------|--------|------|
-| **Workers** | `cloudflare_module` | 서버리스 컴퓨팅, KV/D1 통합 |
-| **Pages** | `cloudflare_pages` | 정적 사이트 + Functions |
+| 옵션 | 방식 | 특징 | 권장 |
+|------|------|------|------|
+| **Workers** | `@cloudflare/vite-plugin` 직접 통합 | 서버리스 컴퓨팅, KV/D1 통합, 최적화 | ✅ |
+| **Pages** | Nitro `cloudflare_pages` preset | 정적 사이트 + Functions | - |
+
+---
 
-## Cloudflare Workers
+## 방식 1: Cloudflare Workers (직접 통합 - 권장)
+
+TanStack Start 공식 권장 방식입니다.
 
 ### 1. 패키지 설치
 
 ```bash
-yarn add @cloudflare/vite-plugin wrangler -D
+pnpm add -D @cloudflare/vite-plugin wrangler
 ```
 
-### 2. Vite 설정 (직접 통합)
+### 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'
+import viteReact from '@vitejs/plugin-react'
 
 export default defineConfig({
   plugins: [
     cloudflare({ viteEnvironment: { name: 'ssr' } }),
     tanstackStart(),
-    react(),
+    viteReact(),
   ],
 })
 ```
@@ -44,77 +88,122 @@ export default defineConfig({
 {
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "my-tanstack-app",
-  "compatibility_date": "2025-01-01",
+  "compatibility_date": "2024-09-19",
   "compatibility_flags": ["nodejs_compat"],
   "main": "@tanstack/react-start/server-entry"
 }
 ```
 
-### 4. 배포
+### 4. 빌드 및 배포
 
 ```bash
 # 빌드
-yarn build
+pnpm build
 
 # 배포
 wrangler deploy
+
+# 또는 한번에
+pnpm build && wrangler deploy
 ```
 
-## Cloudflare Pages
+---
 
-### 1. Nitro 설정
+## 방식 2: Cloudflare Pages (Nitro 레이어)
 
-```typescript
-// nitro.config.ts
-import { defineNitroConfig } from 'nitro/config'
+Nitro 배포 레이어를 사용하는 방식입니다.
 
-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 호환성
-  },
-})
+### 1. Nitro 설치
+
+```bash
+pnpm add nitro@3
 ```
 
-### 2. Vite 설정 (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'
+import viteReact from '@vitejs/plugin-react'
 
 export default defineConfig({
   plugins: [
     tanstackStart(),
     nitro(),
-    react(),
+    viteReact(),
   ],
 })
 ```
 
-### 3. 배포
+### 3. Nitro 설정
+
+```typescript
+// nitro.config.ts
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  preset: 'cloudflare_pages',
+
+  // Nitro v3 필수 설정
+  compatibilityDate: '2024-09-19',
+
+  cloudflare: {
+    deployConfig: true,  // wrangler.json 자동 생성
+    nodeCompat: true,    // Node.js API 호환성
+  },
+})
+```
+
+### 4. 빌드 및 배포
 
 ```bash
 # 빌드
-NITRO_PRESET=cloudflare_pages yarn build
+pnpm build
 
 # Pages 배포
 wrangler pages deploy .output/public
 ```
 
+---
+
 ## Wrangler 설정 상세
 
+### wrangler.jsonc (Workers 직접 통합)
+
+```jsonc
+// wrangler.jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-tanstack-app",
+  "compatibility_date": "2024-09-19",
+  "compatibility_flags": ["nodejs_compat"],
+  "main": "@tanstack/react-start/server-entry",
+
+  // 환경 변수
+  "vars": {
+    "MY_VAR": "value"
+  },
+
+  // KV 스토리지
+  "kv_namespaces": [
+    { "binding": "MY_KV", "id": "your-kv-id" }
+  ],
+
+  // D1 데이터베이스
+  "d1_databases": [
+    { "binding": "DB", "database_name": "my-database", "database_id": "your-database-id" }
+  ]
+}
+```
+
 ### wrangler.toml (Workers)
 
 ```toml
 name = "my-app"
-main = ".output/server/index.mjs"
-compatibility_date = "2025-01-01"
+main = "@tanstack/react-start/server-entry"
+compatibility_date = "2024-09-19"
 compatibility_flags = ["nodejs_compat"]
 
 [vars]
@@ -130,12 +219,12 @@ database_name = "my-database"
 database_id = "your-database-id"
 ```
 
-### wrangler.toml (Pages)
+### wrangler.toml (Pages with Nitro)
 
 ```toml
 name = "my-pages-app"
 pages_build_output_dir = ".output/public"
-compatibility_date = "2025-01-01"
+compatibility_date = "2024-09-19"
 compatibility_flags = ["nodejs_compat"]
 
 [[d1_databases]]
@@ -144,6 +233,8 @@ database_name = "my-database"
 database_id = "your-database-id"
 ```
 
+---
+
 ## KV 스토리지 사용
 
 ### KV 네임스페이스 생성
@@ -152,7 +243,7 @@ database_id = "your-database-id"
 # KV 네임스페이스 생성
 wrangler kv:namespace create "MY_KV"
 
-# wrangler.toml에 바인딩 추가
+# wrangler.jsonc에 바인딩 추가
 ```
 
 ### 코드에서 사용
@@ -174,6 +265,8 @@ export default defineHandler(async (event) => {
 })
 ```
 
+---
+
 ## D1 데이터베이스 사용
 
 ### D1 데이터베이스 생성
@@ -204,6 +297,8 @@ export default defineHandler(async (event) => {
 })
 ```
 
+---
+
 ## 환경변수 관리
 
 ### 로컬 개발
@@ -220,11 +315,16 @@ API_SECRET=your-secret
 # 시크릿 설정
 wrangler secret put API_SECRET
 
-# 일반 변수 (wrangler.toml)
-[vars]
-NODE_ENV = "production"
+# 일반 변수 (wrangler.jsonc)
+{
+  "vars": {
+    "NODE_ENV": "production"
+  }
+}
 ```
 
+---
+
 ## 커스텀 도메인
 
 ### Pages
@@ -245,25 +345,38 @@ routes = [
 ]
 ```
 
+---
+
 ## 개발 서버
 
 ```bash
-# 로컬 개발 (Workers)
+# Workers 로컬 개발
 wrangler dev
 
-# Pages 로컬 개발
+# Pages 로컬 개발 (Nitro 사용 시)
 wrangler pages dev .output/public
 
-# 미니플레어 사용
+# 로컬 모드 (미니플레어 사용)
 wrangler dev --local
 ```
 
+---
+
 ## 트러블슈팅
 
 ### Node.js API 호환성
 
+Workers 직접 통합 시 `wrangler.jsonc`:
+
+```jsonc
+{
+  "compatibility_flags": ["nodejs_compat"]
+}
+```
+
+Nitro 사용 시 `nitro.config.ts`:
+
 ```typescript
-// nitro.config.ts
 import { defineNitroConfig } from 'nitro/config'
 
 export default defineNitroConfig({
@@ -307,12 +420,53 @@ wrangler tail
 wrangler tail --deployment-id [id]
 ```
 
+---
+
 ## CI/CD 설정
 
-### GitHub Actions
+### GitHub Actions (Workers 직접 통합)
+
+```yaml
+name: Deploy to Cloudflare Workers
+
+on:
+  push:
+    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 Workers
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          command: deploy
+```
+
+### GitHub Actions (Pages with Nitro)
 
 ```yaml
-name: Deploy to Cloudflare
+name: Deploy to Cloudflare Pages
 
 on:
   push:
@@ -323,23 +477,52 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@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'
 
-      - run: yarn install
-      - run: yarn build
-        env:
-          NITRO_PRESET: cloudflare_pages
+      - name: Install dependencies
+        run: pnpm install
 
-      - uses: cloudflare/wrangler-action@v3
+      - name: Build
+        run: pnpm build
+
+      - name: Deploy to Pages
+        uses: cloudflare/wrangler-action@v3
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           command: pages deploy .output/public --project-name=my-app
 ```
 
+---
+
+## package.json 스크립트
+
+```json
+{
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && tsc --noEmit",
+    "preview": "vite preview",
+    "deploy": "pnpm build && wrangler deploy"
+  }
+}
+```
+
+---
+
 ## 참고 자료
 
+- [TanStack Start Cloudflare Guide](https://developers.cloudflare.com/workers/frameworks/framework-guides/tanstack-start/)
+- [Cloudflare Vite Plugin](https://developers.cloudflare.com/workers/frameworks/vite/)
 - [Cloudflare Workers 문서](https://developers.cloudflare.com/workers/)
 - [Cloudflare Pages 문서](https://developers.cloudflare.com/pages/)
 - [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)