@kood/claude-code 0.2.4 → 0.3.0

package/templates/tanstack-start/docs/library/t3-env/index.md

@@ -0,0 +1,307 @@
+# t3-env - Type-Safe Environment Variables
+
+> Zod 기반 타입 안전 환경 변수 관리
+
+<context>
+
+**용도:** 서버/클라이언트 환경 변수 분리, 런타임 검증, 타입 안전성
+
+**특징:**
+- Zod 스키마로 검증 + 타입 추론
+- Server 변수 클라이언트 노출 방지
+- Transform & Default 값 지원
+- 프레임워크 무관
+
+</context>
+
+---
+
+<forbidden>
+
+| 분류 | 금지 |
+|------|------|
+| **노출** | Server 변수를 클라이언트에 노출 |
+| **접두사** | Client 변수에 `PUBLIC_` 없이 사용 |
+| **직접 접근** | `process.env` 직접 사용 (env 객체 필수) |
+| **타입** | any 타입으로 env 변수 접근 |
+
+</forbidden>
+
+---
+
+<required>
+
+| 분류 | 필수 |
+|------|------|
+| **설치** | `@t3-oss/env-core zod` |
+| **구조** | `src/env.ts` 파일 생성 |
+| **접두사** | Client 변수: `PUBLIC_` 시작 |
+| **Import** | `import { env } from '@/env'` |
+
+</required>
+
+---
+
+<setup>
+
+## Installation
+
+```bash
+npm install @t3-oss/env-core zod
+```
+
+## Basic Setup
+
+`src/env.ts`:
+
+```typescript
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const env = createEnv({
+  // Server-only variables
+  server: {
+    DATABASE_URL: z.url(),
+    CLERK_SECRET_KEY: z.string().min(1),
+    OPENAI_API_KEY: z.string().min(1),
+  },
+
+  // Client-exposed variables (PUBLIC_ prefix required)
+  clientPrefix: 'PUBLIC_',
+  client: {
+    PUBLIC_API_URL: z.url().default('http://localhost:3000'),
+    PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
+  },
+
+  // Runtime environment
+  runtimeEnv: {
+    // Server
+    DATABASE_URL: process.env.DATABASE_URL,
+    CLERK_SECRET_KEY: process.env.CLERK_SECRET_KEY,
+    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
+    // Client
+    PUBLIC_API_URL: import.meta.env.PUBLIC_API_URL,
+    PUBLIC_CLERK_PUBLISHABLE_KEY: import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY,
+  },
+
+  emptyStringAsUndefined: true,
+})
+```
+
+</setup>
+
+---
+
+<patterns>
+
+## Common Patterns
+
+### Server Function
+
+```typescript
+import { createServerFn } from '@tanstack/start'
+import { env } from '@/env'
+
+export const getUsers = createServerFn({ method: 'GET' }).handler(async () => {
+  const db = await prisma.$connect(env.DATABASE_URL)
+  //                                    ^? string (타입 안전)
+  return db.user.findMany()
+})
+```
+
+### Client Component
+
+```typescript
+import { env } from '@/env'
+
+export const ApiClient = () => {
+  const apiUrl = env.PUBLIC_API_URL
+  //                  ^? string (타입 안전)
+
+  // ❌ Error: server 변수는 클라이언트에서 접근 불가
+  // const dbUrl = env.DATABASE_URL
+}
+```
+
+### Environment-Specific Defaults
+
+```typescript
+server: {
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+}
+```
+
+### Transform Values
+
+```typescript
+server: {
+  PORT: z.string().transform((val) => parseInt(val, 10)).pipe(z.number().positive()),
+  MAX_CONNECTIONS: z.coerce.number().default(10),
+}
+```
+
+### Optional with Fallback
+
+```typescript
+client: {
+  PUBLIC_ANALYTICS_ID: z.string().optional(),
+  PUBLIC_FEATURE_FLAG: z.coerce.boolean().default(false),
+}
+```
+
+</patterns>
+
+---
+
+<examples>
+
+## Real-World Examples
+
+### Database + Auth
+
+```typescript
+// src/env.ts
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.url(),
+    DIRECT_URL: z.url().optional(), // Prisma connection pooling
+    CLERK_SECRET_KEY: z.string().min(1),
+    RESEND_API_KEY: z.string().min(1),
+  },
+  clientPrefix: 'PUBLIC_',
+  client: {
+    PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
+  },
+  runtimeEnv: {
+    DATABASE_URL: process.env.DATABASE_URL,
+    DIRECT_URL: process.env.DIRECT_URL,
+    CLERK_SECRET_KEY: process.env.CLERK_SECRET_KEY,
+    RESEND_API_KEY: process.env.RESEND_API_KEY,
+    PUBLIC_CLERK_PUBLISHABLE_KEY: import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY,
+  },
+  emptyStringAsUndefined: true,
+})
+```
+
+### API Integration
+
+```typescript
+// src/env.ts
+export const env = createEnv({
+  server: {
+    OPENAI_API_KEY: z.string().min(1),
+    STRIPE_SECRET_KEY: z.string().min(1),
+    STRIPE_WEBHOOK_SECRET: z.string().min(1),
+  },
+  clientPrefix: 'PUBLIC_',
+  client: {
+    PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().min(1),
+    PUBLIC_APP_URL: z.url(),
+  },
+  runtimeEnv: {
+    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
+    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
+    STRIPE_WEBHOOK_SECRET: process.env.STRIPE_WEBHOOK_SECRET,
+    PUBLIC_STRIPE_PUBLISHABLE_KEY: import.meta.env.PUBLIC_STRIPE_PUBLISHABLE_KEY,
+    PUBLIC_APP_URL: import.meta.env.PUBLIC_APP_URL,
+  },
+  emptyStringAsUndefined: true,
+})
+```
+
+### Multi-Environment
+
+```typescript
+// src/env.ts
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'production', 'test']),
+    DATABASE_URL: z.url(),
+    REDIS_URL: z.url().optional(), // Production only
+  },
+  clientPrefix: 'PUBLIC_',
+  client: {
+    PUBLIC_API_URL: z.url(),
+    PUBLIC_SENTRY_DSN: z.string().optional(), // Production only
+  },
+  runtimeEnv: {
+    NODE_ENV: process.env.NODE_ENV,
+    DATABASE_URL: process.env.DATABASE_URL,
+    REDIS_URL: process.env.REDIS_URL,
+    PUBLIC_API_URL: import.meta.env.PUBLIC_API_URL,
+    PUBLIC_SENTRY_DSN: import.meta.env.PUBLIC_SENTRY_DSN,
+  },
+  emptyStringAsUndefined: true,
+})
+```
+
+</examples>
+
+---
+
+<validation>
+
+## Validation Patterns
+
+### Email
+
+```typescript
+server: {
+  ADMIN_EMAIL: z.email(),
+  SUPPORT_EMAIL: z.email().default('support@example.com'),
+}
+```
+
+### URL
+
+```typescript
+server: {
+  API_URL: z.url(),
+  WEBHOOK_URL: z.url().optional(),
+}
+```
+
+### Enum
+
+```typescript
+server: {
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']),
+  DATABASE_PROVIDER: z.enum(['postgresql', 'mysql', 'sqlite']),
+}
+```
+
+### Number
+
+```typescript
+server: {
+  PORT: z.coerce.number().positive().default(3000),
+  MAX_UPLOAD_SIZE: z.coerce.number().max(10485760), // 10MB
+}
+```
+
+### Boolean
+
+```typescript
+server: {
+  ENABLE_CACHE: z.coerce.boolean().default(true),
+  DEBUG_MODE: z.coerce.boolean().default(false),
+}
+```
+
+</validation>
+
+---
+
+<tips>
+
+## Tips
+
+| 상황 | 방법 |
+|------|------|
+| **Vercel** | `process.env.VERCEL_URL` → PUBLIC_APP_URL |
+| **Monorepo** | 각 패키지마다 별도 `env.ts` |
+| **Testing** | `.env.test` + `NODE_ENV=test` |
+| **CI/CD** | GitHub Secrets → Environment Variables |
+
+</tips>

package/templates/tanstack-start/docs/library/tanstack-query/index.md

@@ -1,6 +1,6 @@
 # TanStack Query
 
-> 5.x | React Data Fetching Library
+> 5.x | React Data Fetching
 
 @use-query.md
 @use-mutation.md
@@ -9,7 +9,7 @@
 
 ---
 
-## Quick Reference
+<quick_reference>
 
 ```typescript
 // useQuery
@@ -39,37 +39,28 @@ const mutation = useMutation({
     queryClient.setQueryData(['users'], context.previous)
   },
 })
-```
-
-### 설정
-
-```tsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 
+// 설정
 const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
       staleTime: 1000 * 60 * 5,   // 5분
-      gcTime: 1000 * 60 * 30,     // 30분 (이전 cacheTime)
+      gcTime: 1000 * 60 * 30,     // 30분
       retry: 3,
     },
   },
 })
 
-function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <YourApp />
-    </QueryClientProvider>
-  )
-}
-```
+const App = () => (
+  <QueryClientProvider client={queryClient}>
+    <YourApp />
+  </QueryClientProvider>
+)
 
-### Query Keys 패턴
-
-```typescript
+// Query Keys
 ['todos']                       // 단순
 ['todo', { id: 5 }]             // 파라미터
 ['todos', 'list', { filters }]  // 계층적
-['todos', 'detail', todoId]
 ```
+
+</quick_reference>

package/templates/tanstack-start/docs/library/tanstack-query/invalidation.md

@@ -1,6 +1,6 @@
 # TanStack Query - Query 무효화
 
-## 기본 무효화
+<patterns>
 
 ```typescript
 const queryClient = useQueryClient()
@@ -16,52 +16,39 @@ await Promise.all([
 
 // 전체
 queryClient.invalidateQueries()
-```
-
-## 옵션
 
-```typescript
+// 옵션
 queryClient.invalidateQueries({
   queryKey: ['posts'],
   exact: true,  // 정확한 키 매칭만
-  refetchType: 'active',  // 'active'(기본) | 'inactive' | 'all' | 'none'
+  refetchType: 'active',  // 'active' | 'inactive' | 'all' | 'none'
 })
-```
-
-| refetchType | 설명 |
-|-------------|------|
-| active | 렌더링 중인 쿼리만 재조회 (기본) |
-| inactive | 비활성 쿼리만 |
-| all | 모든 매칭 쿼리 |
-| none | 무효화만, 재조회 안함 |
 
-## Query Key 매칭
-
-```typescript
-// prefix 매칭 (todos로 시작하는 모든 쿼리)
-queryClient.invalidateQueries({ queryKey: ['todos'] })
+// Query Key 매칭
+queryClient.invalidateQueries({ queryKey: ['todos'] })  // prefix 매칭
+queryClient.invalidateQueries({ queryKey: ['todos', 'list'], exact: true })  // 정확한 매칭
 
-// 정확한 매칭
-queryClient.invalidateQueries({ queryKey: ['todos', 'list'], exact: true })
-```
-
-## Mutation과 함께
-
-```tsx
+// Mutation과 함께
 useMutation({
   mutationFn: addTodo,
   onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
-  // 또는 onSettled (성공/실패 무관)
-  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),  // 성공/실패 무관
 })
+
+// 직접 업데이트 vs 무효화
+queryClient.setQueryData(['todos'], (old) => [...old, newTodo])  // 더 빠름
+queryClient.invalidateQueries({ queryKey: ['todos'] })  // 서버 데이터 보장
 ```
 
-## 캐시 직접 업데이트 vs 무효화
+</patterns>
 
-```tsx
-// 직접 업데이트 (더 빠름)
-queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+<options>
 
-// 무효화 (서버 데이터 보장)
-queryClient.invalidateQueries({ queryKey: ['todos'] })
-```
+| refetchType | 설명 |
+|-------------|------|
+| active | 렌더링 중인 쿼리만 재조회 (기본) |
+| inactive | 비활성 쿼리만 |
+| all | 모든 매칭 쿼리 |
+| none | 무효화만, 재조회 안함 |
+
+</options>

package/templates/tanstack-start/docs/library/tanstack-query/optimistic-updates.md

@@ -1,39 +1,26 @@
 # TanStack Query - Optimistic Updates
 
-서버 응답 전 UI 즉시 업데이트.
-
-## 패턴
+<patterns>
 
 ```tsx
+// 추가
 useMutation({
   mutationFn: addTodo,
   onMutate: async (newTodo) => {
-    // 1. 진행 중인 refetch 취소
     await queryClient.cancelQueries({ queryKey: ['todos'] })
-
-    // 2. 이전 값 스냅샷
     const previousTodos = queryClient.getQueryData(['todos'])
-
-    // 3. 낙관적 업데이트
     queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
-
-    // 4. context로 이전 값 반환
     return { previousTodos }
   },
   onError: (err, newTodo, context) => {
-    // 5. 에러 시 롤백
     queryClient.setQueryData(['todos'], context.previousTodos)
   },
   onSettled: () => {
-    // 6. 서버와 동기화
     queryClient.invalidateQueries({ queryKey: ['todos'] })
   },
 })
-```
-
-## 삭제
 
-```tsx
+// 삭제
 useMutation({
   mutationFn: deleteTodo,
   onMutate: async (todoId) => {
@@ -49,11 +36,8 @@ useMutation({
   },
   onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
 })
-```
-
-## 토글
 
-```tsx
+// 토글
 useMutation({
   mutationFn: toggleTodo,
   onMutate: async (todoId) => {
@@ -71,11 +55,8 @@ useMutation({
   },
   onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
 })
-```
 
-## 단일 항목 업데이트
-
-```tsx
+// 단일 항목
 useMutation({
   mutationFn: updateTodo,
   onMutate: async (newTodo) => {
@@ -92,3 +73,5 @@ useMutation({
   },
 })
 ```
+
+</patterns>

package/templates/tanstack-start/docs/library/tanstack-query/use-mutation.md

@@ -1,76 +1,63 @@
 # TanStack Query - useMutation
 
-## 기본 사용법
+<patterns>
 
 ```tsx
+// 기본
 const queryClient = useQueryClient()
-
 const mutation = useMutation({
   mutationFn: postTodo,
   onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
 })
-
 mutation.mutate({ title: 'New Todo' })
-```
-
-## 반환값
-
-| 속성 | 설명 |
-|------|------|
-| data | mutation 결과 |
-| error | 에러 객체 |
-| isPending | 실행 중 |
-| isSuccess/isError | 상태 |
-| mutate | 실행 (비동기) |
-| mutateAsync | 실행 (Promise) |
-| reset | 상태 초기화 |
-| variables | 전달된 변수 |
 
-## 콜백
-
-```tsx
+// 콜백
 useMutation({
   mutationFn: updateTodo,
   onMutate: async (newTodo) => {
     // mutation 시작 전 (optimistic update용)
     return { previousData }  // context로 전달
   },
-  onSuccess: (data, variables, context) => {
-    // 성공 시
-  },
-  onError: (error, variables, context) => {
-    // 에러 시 (context로 롤백)
-  },
+  onSuccess: (data, variables, context) => {},
+  onError: (error, variables, context) => {},
   onSettled: (data, error, variables, context) => {
-    // 완료 시 (성공/실패 무관)
     queryClient.invalidateQueries({ queryKey: ['todos'] })
   },
 })
-```
 
-## mutate vs mutateAsync
-
-```tsx
-// 콜백 기반
+// mutate vs mutateAsync
 mutation.mutate(data, {
   onSuccess: (result) => console.log(result),
   onError: (error) => console.log(error),
 })
 
-// Promise 기반
 try {
   const result = await mutation.mutateAsync(data)
 } catch (error) { ... }
-```
 
-## 캐시 업데이트
-
-```tsx
+// 캐시 업데이트
 useMutation({
   mutationFn: patchTodo,
   onSuccess: (data) => {
-    queryClient.invalidateQueries({ queryKey: ['todos'] })  // 목록 무효화
-    queryClient.setQueryData(['todo', { id: data.id }], data)  // 개별 캐시 업데이트
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+    queryClient.setQueryData(['todo', { id: data.id }], data)
   },
 })
 ```
+
+</patterns>
+
+<returns>
+
+| 속성 | 설명 |
+|------|------|
+| data | mutation 결과 |
+| error | 에러 객체 |
+| isPending | 실행 중 |
+| isSuccess/isError | 상태 |
+| mutate | 실행 (비동기) |
+| mutateAsync | 실행 (Promise) |
+| reset | 상태 초기화 |
+| variables | 전달된 변수 |
+
+</returns>

package/templates/tanstack-start/docs/library/tanstack-query/use-query.md

@@ -1,32 +1,17 @@
 # TanStack Query - useQuery
 
-## 기본 사용법
+<patterns>
 
 ```tsx
+// 기본
 const { data, isLoading, error } = useQuery({
   queryKey: ['todos'],
   queryFn: getTodos,
 })
-
 if (isLoading) return <div>Loading...</div>
 if (error) return <div>Error: {error.message}</div>
-```
-
-## 반환값
-
-| 속성 | 설명 |
-|------|------|
-| data | 쿼리 결과 |
-| error | 에러 객체 |
-| isLoading | 첫 로딩 중 |
-| isFetching | 백그라운드 페칭 중 |
-| isError/isSuccess | 상태 |
-| refetch | 수동 리페치 |
-| status | 'pending' \| 'error' \| 'success' |
-
-## 주요 옵션
 
-```tsx
+// 옵션
 useQuery({
   queryKey: ['todos'],
   queryFn: fetchTodos,
@@ -39,12 +24,8 @@ useQuery({
   initialData: [],               // 초기 데이터
   select: (data) => data.filter(t => t.done),  // 데이터 변환
 })
-```
 
-## 패턴
-
-```tsx
-// 파라미터 쿼리
+// 파라미터
 useQuery({
   queryKey: ['todo', todoId],
   queryFn: () => fetchTodoById(todoId),
@@ -56,14 +37,14 @@ const { data: user } = useQuery({ queryKey: ['user', userId], queryFn: ... })
 const { data: posts } = useQuery({
   queryKey: ['posts', user?.id],
   queryFn: () => fetchPostsByUserId(user!.id),
-  enabled: !!user?.id,  // user 로드 후 실행
+  enabled: !!user?.id,
 })
 
-// 병렬 쿼리
+// 병렬
 const usersQuery = useQuery({ queryKey: ['users'], queryFn: fetchUsers })
 const postsQuery = useQuery({ queryKey: ['posts'], queryFn: fetchPosts })
 
-// 동적 병렬 쿼리
+// 동적 병렬
 const userQueries = useQueries({
   queries: userIds.map((id) => ({
     queryKey: ['user', id],
@@ -71,3 +52,19 @@ const userQueries = useQueries({
   })),
 })
 ```
+
+</patterns>
+
+<returns>
+
+| 속성 | 설명 |
+|------|------|
+| data | 쿼리 결과 |
+| error | 에러 객체 |
+| isLoading | 첫 로딩 중 |
+| isFetching | 백그라운드 페칭 중 |
+| isError/isSuccess | 상태 |
+| refetch | 수동 리페치 |
+| status | 'pending' \| 'error' \| 'success' |
+
+</returns>