@kood/claude-code 0.1.6 → 0.1.9

package/templates/tanstack-start/docs/library/tanstack-start/server-functions.md

@@ -1,287 +1,75 @@
 # TanStack Start - Server Functions
 
-> **상위 문서**: [TanStack Start](./index.md)
-
-Server Functions는 서버에서만 실행되는 타입 안전한 함수입니다.
+서버에서만 실행되는 타입 안전한 함수.
 
 ## ⚠️ 필수: TanStack Query 사용
 
-**Server Function을 클라이언트에서 호출할 때는 반드시 TanStack Query를 사용해야 합니다.**
-
-```
-❌ 금지: Server Function 직접 호출
-✅ 필수: useQuery/useMutation과 함께 사용
-```
-
-**이유**:
-- 자동 캐싱 및 중복 요청 제거
-- 로딩/에러 상태 관리
-- 자동 재시도 및 백그라운드 갱신
-- invalidateQueries로 일관된 데이터 동기화
+클라이언트 호출 시 반드시 useQuery/useMutation 사용.
+- 자동 캐싱, 중복 요청 제거, 로딩/에러 상태 관리, invalidateQueries 동기화
 
-## 기본 Server Function
+## 기본 패턴
 
 ```typescript
-import { createServerFn } from '@tanstack/react-start'
-
-// GET 요청 (데이터 조회)
+// GET
 export const getUsers = createServerFn({ method: 'GET' })
-  .handler(async () => {
-    return prisma.user.findMany()
-  })
-
-// POST 요청 (데이터 생성/수정)
-export const createUser = createServerFn({ method: 'POST' })
-  .handler(async () => {
-    return { success: true }
-  })
-```
-
-## Input Validation
-
-### 기본 Validator
-
-```typescript
-import { createServerFn } from '@tanstack/react-start'
-
-export const createUser = createServerFn({ method: 'POST' })
-  .inputValidator((data: { email: string; name: string }) => data)
-  .handler(async ({ data }) => {
-    // data는 타입 안전함
-    return prisma.user.create({ data })
-  })
-```
-
-### Zod Validation 사용
-
-```typescript
-import { createServerFn } from '@tanstack/react-start'
-import { zodValidator } from '@tanstack/react-start/validators'
-import { z } from 'zod'
+  .handler(async () => prisma.user.findMany())
 
+// POST + Zod Validation
 const createUserSchema = z.object({
-  email: z.string().email(),
+  email: z.email(),
   name: z.string().min(1).max(100),
-  bio: z.string().max(500).optional(),
 })
 
 export const createUser = createServerFn({ method: 'POST' })
   .inputValidator(zodValidator(createUserSchema))
-  .handler(async ({ data }) => {
-    return prisma.user.create({ data })
-  })
-```
-
-## FormData 처리
-
-```typescript
-import { createServerFn } from '@tanstack/react-start'
-
-export const submitForm = createServerFn({ method: 'POST' })
-  .inputValidator((formData: FormData) => {
-    const name = formData.get('name') as string
-    const email = formData.get('email') as string
-    return { name, email }
-  })
-  .handler(async ({ data }) => {
-    return prisma.user.create({ data })
-  })
+  .handler(async ({ data }) => prisma.user.create({ data }))
 ```
 
-## 컴포넌트에서 호출 (TanStack Query 필수)
-
-### ✅ 올바른 패턴: useQuery 사용 (데이터 조회)
+## 컴포넌트에서 호출
 
 ```tsx
-import { useQuery } from '@tanstack/react-query'
-import { getServerPosts } from '@/lib/server-functions'
-
-function PostList() {
-  const { data, isLoading, error } = useQuery({
-    queryKey: ['posts'],
-    queryFn: () => getServerPosts(),
-  })
-
-  if (isLoading) return <div>Loading...</div>
-  if (error) return <div>Error: {error.message}</div>
-
-  return (
-    <ul>
-      {data?.map((post) => (
-        <li key={post.id}>{post.title}</li>
-      ))}
-    </ul>
-  )
-}
-```
-
-### ✅ 올바른 패턴: useMutation 사용 (데이터 변경)
-
-```tsx
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { createPost, deletePost } from '@/lib/server-functions'
-
-function PostForm() {
-  const queryClient = useQueryClient()
-
-  const mutation = useMutation({
-    mutationFn: (data: { title: string; content: string }) => createPost({ data }),
-    onSuccess: () => {
-      // 관련 쿼리 무효화로 데이터 동기화
-      queryClient.invalidateQueries({ queryKey: ['posts'] })
-    },
-  })
-
-  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
-    e.preventDefault()
-    const formData = new FormData(e.currentTarget)
-    mutation.mutate({
-      title: formData.get('title') as string,
-      content: formData.get('content') as string,
-    })
-  }
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <input name="title" required />
-      <textarea name="content" required />
-      <button type="submit" disabled={mutation.isPending}>
-        {mutation.isPending ? '저장 중...' : '저장'}
-      </button>
-    </form>
-  )
-}
-```
-
-### ❌ 금지: Server Function 직접 호출
-
-```tsx
-// ❌ 이렇게 하지 마세요!
-function BadExample() {
-  const [posts, setPosts] = useState([])
-  const [loading, setLoading] = useState(false)
-
-  useEffect(() => {
-    setLoading(true)
-    getPosts()
-      .then(setPosts)
-      .finally(() => setLoading(false))
-  }, [])
-
-  // 문제점:
-  // - 중복 요청 발생 가능
-  // - 캐싱 없음
-  // - 에러 처리 수동
-  // - 다른 컴포넌트와 데이터 동기화 안됨
-}
-```
-
-## ⚠️ 함수 분리 시 유의사항
-
-Server Function 내부 로직을 별도 함수로 분리할 때 반드시 아래 규칙을 따르세요.
+// ✅ useQuery (조회)
+const { data, isLoading } = useQuery({
+  queryKey: ['posts'],
+  queryFn: () => getServerPosts(),
+})
 
-### 규칙
+// ✅ useMutation (변경)
+const mutation = useMutation({
+  mutationFn: createPost,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
+})
 
-```
-1. 분리한 함수는 createServerFn 내부에서만 호출
-2. 분리한 함수는 createServerFn으로 감싸지 않음
-3. 분리한 함수는 index.ts에서 export 금지 (프론트엔드 import 방지)
+// ❌ 직접 호출 금지 (캐싱 없음, 동기화 안됨)
 ```
 
-### ✅ 올바른 패턴
+## 함수 분리 규칙
 
 ```typescript
-// services/user/mutations.ts
-
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// 내부 헬퍼 함수 (export 금지!)
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-const validateUserData = async (email: string) => {
-  const existing = await prisma.user.findUnique({ where: { email } })
-  if (existing) throw new Error('Email already exists')
-  return true
-}
+// 내부 헬퍼 (export 금지!)
+const validateUserData = async (email: string) => { ... }
 
-const sendWelcomeEmail = async (userId: string, email: string) => {
-  await emailService.send({
-    to: email,
-    template: 'welcome',
-    data: { userId },
-  })
-}
-
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Server Function (export 가능)
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 export const createUser = createServerFn({ method: 'POST' })
   .inputValidator(createUserSchema)
   .handler(async ({ data }) => {
-    // 내부 헬퍼 함수 호출
     await validateUserData(data.email)
-
-    const user = await prisma.user.create({ data })
-
-    // 내부 헬퍼 함수 호출
-    await sendWelcomeEmail(user.id, user.email)
-
-    return user
-  })
-```
-
-```typescript
-// services/user/index.ts
-
-// ✅ Server Function만 export
-export { createUser, updateUser, deleteUser } from './mutations'
-export { getUsers, getUserById } from './queries'
-
-// ❌ 내부 헬퍼 함수는 export 금지!
-// export { validateUserData, sendWelcomeEmail } from './mutations'
-```
-
-### ❌ 잘못된 패턴
-
-```typescript
-// ❌ 분리한 함수를 createServerFn으로 감싸지 마세요
-export const validateUserData = createServerFn({ method: 'POST' })
-  .handler(async ({ data }) => {
-    // ...
+    return prisma.user.create({ data })
   })
 
-// ❌ 내부 헬퍼 함수를 export 하지 마세요
-export const sendWelcomeEmail = async (userId: string) => {
-  // 프론트엔드에서 import 가능해져 보안 위험!
-}
+// index.ts: Server Function만 export
+export { createUser } from './mutations'
+// ❌ export { validateUserData } 금지
 ```
 
-### 이유
-
-- **보안**: 내부 로직이 프론트엔드 번들에 포함되지 않음
-- **명확한 API**: Server Function만 외부에 노출되어 API 경계가 명확함
-- **트리 쉐이킹**: export하지 않은 함수는 번들에서 제거됨
-
----
-
-## 보안 패턴
-
-### 서버 전용 데이터 보호
+## 보안
 
 ```tsx
-// ❌ 잘못된 방법 - 클라이언트에 노출됨
-export const Route = createFileRoute('/users')({
-  loader: () => {
-    const secret = process.env.SECRET // 클라이언트에 노출!
-    return fetch(`/api/users?key=${secret}`)
-  },
-})
-
-// ✅ 올바른 방법 - 서버 함수 사용
-const getUsersSecurely = createServerFn().handler(() => {
-  const secret = process.env.SECRET // 서버에서만 접근
-  return fetch(`/api/users?key=${secret}`)
-})
+// ❌ loader에서 환경변수 직접 사용 (노출됨)
+loader: () => { const secret = process.env.SECRET }
 
-export const Route = createFileRoute('/users')({
-  loader: () => getUsersSecurely(),
+// ✅ Server Function 사용
+const fn = createServerFn().handler(() => {
+  const secret = process.env.SECRET // 서버에서만
 })
 ```

package/templates/tanstack-start/docs/library/tanstack-start/setup.md

@@ -1,15 +1,13 @@
 # TanStack Start - 설치 및 설정
 
-> **상위 문서**: [TanStack Start](./index.md)
-
-## 패키지 설치
+## 설치
 
 ```bash
 yarn add @tanstack/react-start @tanstack/react-router vinxi
 yarn add -D vite @vitejs/plugin-react vite-tsconfig-paths
 ```
 
-## Vite 설정
+## 설정
 
 ```typescript
 // vite.config.ts
@@ -19,19 +17,11 @@ import { tanstackStart } from '@tanstack/react-start/plugin/vite'
 import viteReact from '@vitejs/plugin-react'
 
 export default defineConfig({
-  server: {
-    port: 3000,
-  },
-  plugins: [
-    tsConfigPaths(),
-    tanstackStart(),
-    viteReact(),
-  ],
+  server: { port: 3000 },
+  plugins: [tsConfigPaths(), tanstackStart(), viteReact()],
 })
 ```
 
-## TypeScript 설정
-
 ```json
 // tsconfig.json
 {
@@ -40,35 +30,12 @@ export default defineConfig({
     "module": "ESNext",
     "moduleResolution": "bundler",
     "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
     "jsx": "react-jsx",
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "include": ["src/**/*"]
+    "paths": { "@/*": ["./src/*"] }
+  }
 }
 ```
 
-## 프로젝트 구조
-
-```
-project/
-├── src/
-│   ├── routes/
-│   │   ├── __root.tsx
-│   │   ├── index.tsx
-│   │   └── about.tsx
-│   ├── lib/
-│   │   └── server-functions.ts
-│   └── start.ts
-├── vite.config.ts
-├── tsconfig.json
-└── package.json
-```
-
 ## 환경 변수 검증
 
 ```typescript

package/templates/tanstack-start/docs/library/zod/complex-types.md

@@ -1,204 +1,80 @@
 # Zod - 복합 타입
 
-> **상위 문서**: [Zod](./index.md)
-
 ## 객체
 
 ```typescript
 const UserSchema = z.object({
   name: z.string(),
-  email: z.email(),  // v4 새 API
-  age: z.number().optional(),  // 선택적 필드
-})
-
-// 검증
-const result = UserSchema.parse({
-  name: 'john',
-  email: 'john@example.com',
-  age: 25,
-})
-
-// 안전한 검증
-const safeResult = UserSchema.safeParse(data)
-if (safeResult.success) {
-  console.log(safeResult.data)
-} else {
-  console.log(safeResult.error)
-}
-```
-
-### 객체 메서드
-
-```typescript
-// 부분 객체 (모든 필드가 optional)
-const PartialUser = UserSchema.partial()
-
-// 필수 객체 (모든 필드가 required)
-const RequiredUser = UserSchema.required()
-
-// 필드 선택
-const UserName = UserSchema.pick({ name: true })
-
-// 필드 제외
-const UserWithoutEmail = UserSchema.omit({ email: true })
-
-// 확장
-const ExtendedUser = UserSchema.extend({
-  role: z.enum(['admin', 'user']),
+  email: z.email(),
+  age: z.number().optional(),
 })
 
-// 병합
-const MergedSchema = UserSchema.merge(AnotherSchema)
-```
-
-### Strict/Loose 객체 (v4)
+// 메서드
+UserSchema.partial()              // 모든 필드 optional
+UserSchema.required()             // 모든 필드 required
+UserSchema.pick({ name: true })   // 특정 필드만
+UserSchema.omit({ email: true })  // 특정 필드 제외
+UserSchema.extend({ role: z.enum(['admin', 'user']) })
+UserSchema.merge(AnotherSchema)
 
-```typescript
-// v3
-z.object({ name: z.string() }).strict()     // 추가 키 에러
-z.object({ name: z.string() }).passthrough() // 추가 키 통과
-
-// v4 - 새로운 API
+// v4 Strict/Loose
 z.strictObject({ name: z.string() })  // 추가 키 에러
 z.looseObject({ name: z.string() })   // 추가 키 통과
 ```
 
-## 배열
+## 배열/튜플
 
 ```typescript
 z.array(z.string())
-z.array(z.number()).min(1)     // 최소 1개
-z.array(z.number()).max(10)    // 최대 10개
-z.array(z.number()).length(5)  // 정확히 5개
-z.array(z.number()).nonempty() // 비어있지 않음
-```
+z.array(z.number()).min(1).max(10).length(5).nonempty()
 
-## 튜플
-
-```typescript
-const tuple = z.tuple([
-  z.string(),  // 첫 번째 요소
-  z.number(),  // 두 번째 요소
-])
-
-type Tuple = z.infer<typeof tuple>
-// [string, number]
+z.tuple([z.string(), z.number()])  // [string, number]
 ```
 
 ## 유니온
 
 ```typescript
-const StringOrNumber = z.union([z.string(), z.number()])
-// 또는
-const StringOrNumber = z.string().or(z.number())
-
-type StringOrNumber = z.infer<typeof StringOrNumber>
-// string | number
-```
+z.union([z.string(), z.number()])
+z.string().or(z.number())
 
-## Discriminated Union
-
-```typescript
-const Shape = z.discriminatedUnion('type', [
+// Discriminated Union
+z.discriminatedUnion('type', [
   z.object({ type: z.literal('circle'), radius: z.number() }),
   z.object({ type: z.literal('rectangle'), width: z.number(), height: z.number() }),
 ])
-
-type Shape = z.infer<typeof Shape>
-// { type: 'circle'; radius: number } | { type: 'rectangle'; width: number; height: number }
-```
-
-### v4 향상된 Discriminated Union
-
-```typescript
-// 유니온 및 파이프 discriminator 지원
-const MyResult = z.discriminatedUnion("status", [
-  // 단순 리터럴
-  z.object({ status: z.literal("aaa"), data: z.string() }),
-  // 유니온 discriminator
-  z.object({ status: z.union([z.literal("bbb"), z.literal("ccc")]) }),
-  // 파이프 discriminator
-  z.object({ status: z.literal("fail").transform(val => val.toUpperCase()) }),
-])
-
-// 중첩 discriminated union
-const BaseError = z.object({ status: z.literal("failed"), message: z.string() })
-
-const MyResult2 = z.discriminatedUnion("status", [
-  z.object({ status: z.literal("success"), data: z.string() }),
-  z.discriminatedUnion("code", [
-    BaseError.extend({ code: z.literal(400) }),
-    BaseError.extend({ code: z.literal(401) }),
-    BaseError.extend({ code: z.literal(500) })
-  ])
-])
 ```
 
 ## Enum
 
 ```typescript
-// 문자열 enum
-const FishEnum = z.enum(['Salmon', 'Tuna', 'Trout'])
-
-FishEnum.parse('Salmon') // => "Salmon"
-FishEnum.parse('Swordfish') // => ❌ throws
-
-type Fish = z.infer<typeof FishEnum>
-// 'Salmon' | 'Tuna' | 'Trout'
+const Status = z.enum(['pending', 'done', 'cancelled'])
+type Status = z.infer<typeof Status>  // 'pending' | 'done' | 'cancelled'
 
 // Native enum
-enum Fruits {
-  Apple,
-  Banana,
-}
-const FruitSchema = z.nativeEnum(Fruits)
+enum Fruits { Apple, Banana }
+z.nativeEnum(Fruits)
 ```
 
-## Record
+## Record/Map/Set
 
 ```typescript
-const UserStore = z.record(z.string(), z.object({
-  name: z.string(),
-}))
-
-type UserStore = z.infer<typeof UserStore>
+z.record(z.string(), z.object({ name: z.string() }))
 // { [key: string]: { name: string } }
 
-// 사용
-const userStore: UserStore = {}
-userStore['77d2586b-9e8e-4ecf-8b21-ea7e0530eadd'] = {
-  name: 'Carlotta',
-} // passes
-
-userStore['77d2586b-9e8e-4ecf-8b21-ea7e0530eadd'] = {
-  whatever: 'Ice cream sundae',
-} // TypeError
+z.map(z.string(), z.number())  // Map<string, number>
+z.set(z.number())              // Set<number>
 ```
 
-## Map & Set
+## 재귀 스키마
 
 ```typescript
-// Map
-const stringNumberMap = z.map(z.string(), z.number())
-type StringNumberMap = z.infer<typeof stringNumberMap>
-// Map<string, number>
-
-// Set
-const numberSet = z.set(z.number())
-type NumberSet = z.infer<typeof numberSet>
-// Set<number>
-```
-
-## 재귀 스키마 (JSON)
-
-```typescript
-const literalSchema = z.union([z.string(), z.number(), z.boolean(), z.null()])
-type Literal = z.infer<typeof literalSchema>
-type Json = Literal | { [key: string]: Json } | Json[]
+type Json = string | number | boolean | null | { [key: string]: Json } | Json[]
 
 const jsonSchema: z.ZodType<Json> = z.lazy(() =>
-  z.union([literalSchema, z.array(jsonSchema), z.record(jsonSchema)])
+  z.union([
+    z.string(), z.number(), z.boolean(), z.null(),
+    z.array(jsonSchema),
+    z.record(jsonSchema)
+  ])
 )
-
-jsonSchema.parse({ foo: [1, 2, { bar: 'baz' }] })
 ```