@kood/claude-code 0.1.2 → 0.1.3

package/templates/tanstack-start/docs/guides/best-practices.md

@@ -146,6 +146,49 @@ services/
     └── mutations.ts
 ```
 
+## 코드 작성 규칙
+
+### UTF-8 인코딩 유지
+
+모든 한글 텍스트는 UTF-8 인코딩이 깨지지 않도록 작성합니다.
+
+### 한글 주석 작성 규칙
+
+**묶음 단위로 한글 주석을 작성합니다** (너무 세세하게 X)
+
+```typescript
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 사용자 관련 상태
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+const [user, setUser] = useState<User | null>(null)
+const [isLoading, setIsLoading] = useState(false)
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 데이터 조회
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+const { data: users } = useQuery({
+  queryKey: ['users'],
+  queryFn: () => getUsers(),
+})
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 이벤트 핸들러
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+const handleSubmit = () => { /* ... */ }
+const handleDelete = () => { /* ... */ }
+```
+
+### ❌ 너무 세세한 주석 (금지)
+
+```typescript
+// ❌ 이렇게 하지 마세요
+const [user, setUser] = useState(null)  // 사용자 상태
+const [isLoading, setIsLoading] = useState(false)  // 로딩 상태
+const [error, setError] = useState(null)  // 에러 상태
+```
+
+---
+
 ## TypeScript Standards
 
 ### Use `const` for Functions
@@ -234,7 +277,164 @@ const UsersPage = (): JSX.Element => {
 }
 ```
 
-### Page Hook
+### Custom Hook 작성 규칙
+
+**Purpose**: 페이지 또는 섹션의 **모든 로직, 상태, 라이프사이클**을 중앙화합니다.
+
+- 페이지 훅: 페이지 전체 로직 담당
+- 섹션 훅: 해당 섹션의 로직만 담당 (섹션으로 분리한 경우)
+
+### ⚠️ 필수: Custom Hook 내부 순서
+
+훅 내부 코드는 **반드시 아래 순서**를 따릅니다:
+
+```
+1. State (useState, zustand store)
+2. Global Hooks (useParams, useNavigate, useQueryClient 등)
+3. React Query (useQuery → useMutation 순서)
+4. Event Handlers & Functions
+5. useMemo
+6. useEffect
+```
+
+### ✅ 올바른 Custom Hook 예시
+
+```typescript
+// routes/users/-hooks/use-users.ts
+import { useState, useMemo, useEffect, useCallback } from 'react'
+import { useParams, useNavigate } from '@tanstack/react-router'
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { useServerFn } from '@tanstack/react-start'
+import { useAuthStore } from '@/stores/auth'
+import { getUsers, createUser, deleteUser } from '@/services/user'
+import type { User } from '@/types'
+
+interface UseUsersReturn {
+  users: User[] | undefined
+  filteredUsers: User[]
+  isLoading: boolean
+  error: Error | null
+  search: string
+  setSearch: (value: string) => void
+  handleCreate: (data: { email: string; name: string }) => void
+  handleDelete: (id: string) => void
+  isCreating: boolean
+  isDeleting: boolean
+}
+
+export const useUsers = (): UseUsersReturn => {
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 1. State (useState, zustand store)
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const [search, setSearch] = useState('')
+  const { user: currentUser } = useAuthStore()
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 2. Global Hooks
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const params = useParams({ from: '/users/$id' })
+  const navigate = useNavigate()
+  const queryClient = useQueryClient()
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 3. React Query (useQuery → useMutation)
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const getUsersFn = useServerFn(getUsers)
+  const createUserFn = useServerFn(createUser)
+  const deleteUserFn = useServerFn(deleteUser)
+
+  const { data: users, isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => getUsersFn(),
+  })
+
+  const createMutation = useMutation({
+    mutationFn: createUserFn,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    },
+  })
+
+  const deleteMutation = useMutation({
+    mutationFn: deleteUserFn,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    },
+  })
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 4. Event Handlers & Functions
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const handleCreate = useCallback(
+    (data: { email: string; name: string }) => {
+      createMutation.mutate({ data })
+    },
+    [createMutation]
+  )
+
+  const handleDelete = useCallback(
+    (id: string) => {
+      deleteMutation.mutate({ data: id })
+    },
+    [deleteMutation]
+  )
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 5. useMemo
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const filteredUsers = useMemo(() => {
+    if (!users) return []
+    if (!search) return users
+    return users.filter((user) =>
+      user.name.toLowerCase().includes(search.toLowerCase())
+    )
+  }, [users, search])
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 6. useEffect
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  useEffect(() => {
+    if (!currentUser) {
+      navigate({ to: '/login' })
+    }
+  }, [currentUser, navigate])
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Return
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  return {
+    users,
+    filteredUsers,
+    isLoading,
+    error,
+    search,
+    setSearch,
+    handleCreate,
+    handleDelete,
+    isCreating: createMutation.isPending,
+    isDeleting: deleteMutation.isPending,
+  }
+}
+```
+
+### ❌ 잘못된 순서 (금지)
+
+```typescript
+// ❌ 순서가 뒤섞인 잘못된 예시
+export const useBadHook = () => {
+  const queryClient = useQueryClient()  // ❌ Global Hook이 먼저
+
+  useEffect(() => { /* ... */ }, [])    // ❌ useEffect가 중간에
+
+  const [state, setState] = useState()  // ❌ State가 나중에
+
+  const { data } = useQuery({ /* ... */ })  // ❌ Query가 Effect 다음에
+
+  const computed = useMemo(() => {}, [])  // ❌ useMemo 위치 잘못됨
+}
+```
+
+### Page Hook (간단한 예시)
 
 ```typescript
 // routes/users/-hooks/use-users.ts
@@ -253,8 +453,10 @@ interface UseUsersReturn {
 }
 
 export const useUsers = (): UseUsersReturn => {
+  // 2. Global Hooks
   const queryClient = useQueryClient()
 
+  // 3. React Query (useQuery → useMutation)
   const { data: users, isLoading, error } = useQuery({
     queryKey: ['users'],
     queryFn: () => getUsers(),

package/templates/tanstack-start/docs/guides/env-setup.md

@@ -0,0 +1,450 @@
+# TanStack Start - 환경 변수 설정
+
+> **상위 문서**: [Best Practices](./best-practices.md)
+
+TanStack Start는 Vite 기반으로 동작하며, 환경별 `.env` 파일을 통해 환경 변수를 관리합니다.
+
+---
+
+## 핵심 개념
+
+### 서버 vs 클라이언트 환경 변수
+
+```
+서버 전용     → process.env.DATABASE_URL     (노출 X)
+클라이언트용  → import.meta.env.VITE_*       (노출 O)
+```
+
+| 접근 방식 | 접근 가능 위치 | 용도 |
+|-----------|---------------|------|
+| `process.env.*` | Server Function, 서버 코드 | DB 연결, API 키, 시크릿 |
+| `import.meta.env.VITE_*` | 클라이언트 + 서버 | 공개 설정, API URL |
+
+⚠️ **중요**: `VITE_` 접두사가 없는 변수는 클라이언트에 노출되지 않습니다.
+
+---
+
+## 환경 파일 구조
+
+```
+프로젝트/
+├── .env                    # 기본 환경 변수 (공통, 커밋 O)
+├── .env.development        # 개발 환경 (커밋 O)
+├── .env.production         # 프로덕션 환경 (커밋 O)
+├── .env.local              # 로컬 오버라이드 (커밋 X, gitignore)
+├── .env.development.local  # 개발 로컬 오버라이드 (커밋 X)
+├── .env.production.local   # 프로덕션 로컬 오버라이드 (커밋 X)
+└── app/
+    └── config/
+        └── env.ts          # 환경 변수 검증 및 타입
+```
+
+### 로드 우선순위 (높은 순)
+
+```
+1. .env.{mode}.local    # 최우선 (gitignore)
+2. .env.local           # 로컬 오버라이드 (gitignore)
+3. .env.{mode}          # 환경별 설정
+4. .env                 # 기본 설정
+```
+
+---
+
+## 환경 변수 파일 예시
+
+### .env (기본 설정, 커밋용)
+
+```env
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 기본 환경 변수 (모든 환경에서 공통)
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+# 클라이언트 공개 설정 (VITE_ 접두사 필수)
+VITE_APP_NAME=My TanStack App
+VITE_API_URL=https://api.example.com
+
+# 서버 설정 템플릿 (실제 값은 .env.local에서 오버라이드)
+DATABASE_URL=postgresql://localhost:5432/myapp_dev
+REDIS_URL=redis://localhost:6379
+```
+
+### .env.development
+
+```env
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 개발 환경 설정
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+NODE_ENV=development
+
+# 클라이언트 공개 설정
+VITE_APP_NAME=My App (Dev)
+VITE_API_URL=http://localhost:3001/api
+VITE_DEBUG=true
+
+# 서버 설정
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp_dev
+DATABASE_POOL_SIZE=5
+
+# 개발용 설정
+LOG_LEVEL=debug
+CORS_ORIGIN=http://localhost:3000
+```
+
+### .env.production
+
+```env
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 프로덕션 환경 설정
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+NODE_ENV=production
+
+# 클라이언트 공개 설정
+VITE_APP_NAME=My App
+VITE_API_URL=https://api.myapp.com
+VITE_DEBUG=false
+
+# 서버 설정 (실제 값은 CI/CD 또는 호스팅 환경에서 주입)
+DATABASE_POOL_SIZE=20
+
+# 프로덕션 설정
+LOG_LEVEL=info
+CORS_ORIGIN=https://myapp.com
+```
+
+### .env.local (gitignore, 실제 시크릿)
+
+```env
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# 로컬 개발용 시크릿 (절대 커밋 금지!)
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+# 데이터베이스
+DATABASE_URL=postgresql://user:realpassword@localhost:5432/myapp_local
+
+# 인증
+JWT_SECRET=your-super-secret-jwt-key-at-least-32-chars
+AUTH_SECRET=your-auth-secret-key
+
+# 외부 서비스 API 키
+OPENAI_API_KEY=sk-xxx
+STRIPE_SECRET_KEY=sk_test_xxx
+```
+
+---
+
+## 타입 안전한 환경 변수 (Zod)
+
+### app/config/env.ts
+
+```typescript
+// app/config/env.ts
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 환경 변수 검증 및 타입 정의
+// 서버/클라이언트 환경 변수를 분리하여 관리합니다
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+import { z } from 'zod'
+
+// 서버 환경 변수 스키마
+const serverEnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+
+  // 데이터베이스
+  DATABASE_URL: z.string().url(),
+  DATABASE_POOL_SIZE: z.coerce.number().default(10),
+
+  // 인증
+  JWT_SECRET: z.string().min(32),
+  AUTH_SECRET: z.string().min(16).optional(),
+
+  // 외부 서비스 (선택적)
+  OPENAI_API_KEY: z.string().optional(),
+  STRIPE_SECRET_KEY: z.string().optional(),
+
+  // 설정
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  CORS_ORIGIN: z.string().default('*'),
+})
+
+// 클라이언트 환경 변수 스키마 (VITE_ 접두사)
+const clientEnvSchema = z.object({
+  VITE_APP_NAME: z.string(),
+  VITE_API_URL: z.string().url(),
+  VITE_DEBUG: z.coerce.boolean().default(false),
+})
+
+// 타입 추출
+export type ServerEnv = z.infer<typeof serverEnvSchema>
+export type ClientEnv = z.infer<typeof clientEnvSchema>
+
+// 서버 환경 변수 파싱 (Server Function에서만 호출)
+const parseServerEnv = (): ServerEnv => {
+  const result = serverEnvSchema.safeParse(process.env)
+
+  if (!result.success) {
+    console.error('❌ 서버 환경 변수 검증 실패:')
+    console.error(result.error.format())
+    throw new Error('Server environment validation failed')
+  }
+
+  return result.data
+}
+
+// 클라이언트 환경 변수 파싱
+const parseClientEnv = (): ClientEnv => {
+  const result = clientEnvSchema.safeParse(import.meta.env)
+
+  if (!result.success) {
+    console.error('❌ 클라이언트 환경 변수 검증 실패:')
+    console.error(result.error.format())
+    throw new Error('Client environment validation failed')
+  }
+
+  return result.data
+}
+
+// Export (서버 환경 변수는 lazy evaluation)
+let _serverEnv: ServerEnv | null = null
+
+export const getServerEnv = (): ServerEnv => {
+  if (!_serverEnv) {
+    _serverEnv = parseServerEnv()
+  }
+  return _serverEnv
+}
+
+export const clientEnv = parseClientEnv()
+```
+
+---
+
+## 사용 예시
+
+### Server Function에서 사용
+
+```typescript
+// app/server-functions/users.ts
+import { createServerFn } from '@tanstack/react-start'
+import { getServerEnv } from '~/config/env'
+
+export const getUsers = createServerFn({ method: 'GET' })
+  .handler(async () => {
+    const env = getServerEnv()
+
+    // ✅ 서버 전용 환경 변수 사용
+    const config = {
+      url: env.DATABASE_URL,
+      maxConnections: env.DATABASE_POOL_SIZE,
+      ssl: env.NODE_ENV === 'production',
+    }
+
+    const db = await createConnection(config)
+    return db.user.findMany()
+  })
+```
+
+### 클라이언트 컴포넌트에서 사용
+
+```tsx
+// app/components/AppHeader.tsx
+import { clientEnv } from '~/config/env'
+
+export const AppHeader = () => {
+  return (
+    <header>
+      {/* ✅ VITE_ 접두사 변수만 접근 가능 */}
+      <h1>{clientEnv.VITE_APP_NAME}</h1>
+
+      {clientEnv.VITE_DEBUG && (
+        <span className="text-red-500">Debug Mode</span>
+      )}
+    </header>
+  )
+}
+```
+
+### 직접 접근 (검증 없이)
+
+```tsx
+// Server Function 내부
+const dbUrl = process.env.DATABASE_URL  // ✅ 서버에서만
+
+// 클라이언트 컴포넌트
+const appName = import.meta.env.VITE_APP_NAME  // ✅ VITE_ 접두사만
+```
+
+---
+
+## 인증 설정 예시
+
+### 서버 측 인증 설정
+
+```typescript
+// app/lib/auth.ts
+import { getServerEnv } from '~/config/env'
+
+export const getAuthConfig = () => {
+  const env = getServerEnv()
+
+  return {
+    secret: env.AUTH_SECRET,
+    providers: {
+      auth0: {
+        domain: process.env.AUTH0_DOMAIN,
+        clientId: process.env.AUTH0_CLIENT_ID,
+        clientSecret: process.env.AUTH0_CLIENT_SECRET,  // ✅ 서버 전용
+      },
+    },
+  }
+}
+```
+
+### 클라이언트 측 인증 Provider
+
+```tsx
+// app/components/AuthProvider.tsx
+export const AuthProvider = ({ children }: { children: React.ReactNode }) => {
+  return (
+    <Auth0Provider
+      domain={import.meta.env.VITE_AUTH0_DOMAIN}
+      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
+      // ❌ clientSecret은 여기에 없음 - 서버에만 존재
+    >
+      {children}
+    </Auth0Provider>
+  )
+}
+```
+
+---
+
+## 필수 환경 변수 검증
+
+### 앱 시작 시 검증
+
+```typescript
+// app/config/validation.ts
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 필수 환경 변수 검증
+// 앱 시작 시 누락된 환경 변수를 조기에 발견합니다
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const requiredServerEnv = [
+  'DATABASE_URL',
+  'JWT_SECRET',
+] as const
+
+const requiredClientEnv = [
+  'VITE_APP_NAME',
+  'VITE_API_URL',
+] as const
+
+export const validateEnv = () => {
+  // 서버 환경 변수 검증
+  for (const key of requiredServerEnv) {
+    if (!process.env[key]) {
+      throw new Error(`❌ Missing required server env: ${key}`)
+    }
+  }
+
+  // 클라이언트 환경 변수 검증
+  for (const key of requiredClientEnv) {
+    if (!import.meta.env[key]) {
+      throw new Error(`❌ Missing required client env: ${key}`)
+    }
+  }
+
+  console.log('✅ Environment variables validated')
+}
+```
+
+---
+
+## .gitignore 설정
+
+```gitignore
+# 환경 변수 파일
+.env.local
+.env.*.local
+.env.development.local
+.env.production.local
+
+# 커밋해도 되는 파일 (시크릿 없음)
+!.env
+!.env.development
+!.env.production
+```
+
+⚠️ **중요**: `.env.development`와 `.env.production`에는 **실제 시크릿을 절대 넣지 마세요!**
+- 실제 시크릿은 `.env.local` 또는 CI/CD 환경 변수로 관리
+- `.env.*` 파일에는 플레이스홀더나 기본값만 포함
+
+---
+
+## 빌드 모드
+
+### 개발 서버
+
+```bash
+# 기본 development 모드
+npm run dev
+
+# .env.development + .env 로드
+```
+
+### 프로덕션 빌드
+
+```bash
+# 기본 production 모드
+npm run build
+
+# .env.production + .env 로드
+```
+
+### 커스텀 모드
+
+```bash
+# staging 모드로 빌드
+npm run build -- --mode staging
+
+# .env.staging + .env 로드
+```
+
+```env
+# .env.staging
+NODE_ENV=production
+VITE_APP_NAME=My App (Staging)
+VITE_API_URL=https://staging-api.myapp.com
+```
+
+---
+
+## TypeScript 타입 정의
+
+### vite-env.d.ts
+
+```typescript
+// app/vite-env.d.ts
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_APP_NAME: string
+  readonly VITE_API_URL: string
+  readonly VITE_DEBUG: string
+  readonly VITE_AUTH0_DOMAIN?: string
+  readonly VITE_AUTH0_CLIENT_ID?: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+```
+
+---
+
+## 관련 문서
+
+- [Best Practices](./best-practices.md)
+- [Server Functions](../library/tanstack-start/server-functions.md)
+- [Vite 환경 변수 공식 문서](https://vitejs.dev/guide/env-and-mode.html)