@kood/claude-code 0.6.6 → 0.7.0

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/server-serialization.md

@@ -1,38 +1,73 @@
 ---
-title: Minimize Serialization at RSC Boundaries
+title: Minimize Serialization in Loader Data
 impact: HIGH
 impactDescription: reduces data transfer size
-tags: server, rsc, serialization, props
+tags: server, loader, serialization, tanstack-start
 ---
 
-## RSC 경계에서 직렬화 최소화
+## Loader 데이터 직렬화 최소화
 
-React Server/Client 경계는 모든 객체 속성을 문자열로 직렬화하여 HTML 응답 및 후속 RSC 요청에 포함합니다. 이 직렬화된 데이터는 페이지 가중치와 로드 시간에 직접 영향을 미치므로 **크기가 매우 중요합니다**. 클라이언트가 실제로 사용하는 필드만 전달하세요.
+TanStack Start의 loader에서 반환하는 데이터는 서버 → 클라이언트로 직렬화되어 전달됩니다. 이 직렬화된 데이터는 HTML 응답 크기와 하이드레이션 시간에 직접 영향을 미치므로 **클라이언트가 실제로 사용하는 필드만 반환하세요**.
 
 **❌ 잘못된 예시 (50개 필드 모두 직렬화):**
 
-```tsx
-async function Page() {
-  const user = await fetchUser()  // 50개 필드
-  return <Profile user={user} />
-}
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+import { createFileRoute } from '@tanstack/react-router'
+
+const getUser = createServerFn().handler(async () => {
+  return await db.user.findUnique({ where: { id: '1' } }) // 50개 필드
+})
+
+export const Route = createFileRoute('/profile')({
+  loader: async () => {
+    const user = await getUser()
+    return { user } // 50개 필드 모두 직렬화
+  }
+})
 
-'use client'
-function Profile({ user }: { user: User }) {
-  return <div>{user.name}</div>  // 1개 필드만 사용
+function ProfilePage() {
+  const { user } = Route.useLoaderData()
+  return <div>{user.name}</div> // 1개 필드만 사용
 }
 ```
 
-**✅ 올바른 예시 (1개 필드만 직렬화):**
+**✅ 올바른 예시 (필요한 필드만 직렬화):**
 
-```tsx
-async function Page() {
-  const user = await fetchUser()
-  return <Profile name={user.name} />
-}
+```typescript
+const getUser = createServerFn().handler(async () => {
+  const user = await db.user.findUnique({ where: { id: '1' } })
+  return { name: user.name, email: user.email } // 필요한 필드만
+})
+
+export const Route = createFileRoute('/profile')({
+  loader: async () => {
+    const user = await getUser()
+    return { userName: user.name, userEmail: user.email }
+  }
+})
 
-'use client'
-function Profile({ name }: { name: string }) {
-  return <div>{name}</div>
+function ProfilePage() {
+  const { userName, userEmail } = Route.useLoaderData()
+  return (
+    <div>
+      <div>{userName}</div>
+      <div>{userEmail}</div>
+    </div>
+  )
 }
 ```
+
+**✅ Server Function에서 select로 필드 제한:**
+
+```typescript
+const getUser = createServerFn().handler(async () => {
+  // DB 쿼리 자체에서 필드 제한 (가장 효율적)
+  return await db.user.findUnique({
+    where: { id: '1' },
+    select: { name: true, email: true, avatar: true }
+  })
+})
+```
+
+loader 데이터가 클수록 SSR HTML 크기, 하이드레이션 시간, 클라이언트 네비게이션 데이터 전송량이 모두 증가합니다.

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/server-streaming.md

@@ -0,0 +1,84 @@
+---
+title: Stream Data from Server Functions
+impact: MEDIUM
+impactDescription: progressive data delivery
+tags: server, streaming, async-generator, ReadableStream, tanstack-start
+---
+
+## Server Functions에서 데이터 스트리밍
+
+대량 데이터나 실시간 업데이트가 필요한 경우, Server Function에서 스트리밍으로 데이터를 점진적 전달합니다.
+
+**❌ 잘못된 예시 (전체 데이터 대기):**
+
+```typescript
+const generateReport = createServerFn({ method: 'POST' })
+  .handler(async () => {
+    const items = []
+    for (const chunk of await processLargeDataset()) {
+      items.push(chunk)
+    }
+    return items // 전체 처리 완료까지 대기
+  })
+```
+
+**✅ 올바른 예시 (async generator로 스트리밍):**
+
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+
+const generateReport = createServerFn({ method: 'POST' })
+  .handler(async function* () {
+    yield { status: 'processing', progress: 0 }
+
+    for await (const chunk of processLargeDataset()) {
+      yield { status: 'processing', data: chunk, progress: chunk.index }
+    }
+
+    yield { status: 'complete', progress: 100 }
+  })
+```
+
+**✅ ReadableStream 방식 (세밀한 제어):**
+
+```typescript
+const streamResponse = createServerFn({ method: 'POST' })
+  .handler(async () => {
+    return new ReadableStream({
+      start(controller) {
+        const encoder = new TextEncoder()
+        controller.enqueue(encoder.encode(JSON.stringify({ msg: 'chunk 1' })))
+        controller.enqueue(encoder.encode(JSON.stringify({ msg: 'chunk 2' })))
+        controller.close()
+      }
+    })
+  })
+```
+
+**클라이언트에서 스트림 소비:**
+
+```tsx
+function ReportGenerator() {
+  const [chunks, setChunks] = useState<ReportChunk[]>([])
+
+  const handleGenerate = async () => {
+    const stream = await generateReport()
+    for await (const chunk of stream) {
+      setChunks(prev => [...prev, chunk])
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={handleGenerate}>Generate</button>
+      {chunks.map((chunk, i) => <ChunkDisplay key={i} chunk={chunk} />)}
+    </div>
+  )
+}
+```
+
+**사용 시점:** AI 응답 스트리밍, 대용량 CSV/JSON 내보내기, 실시간 진행률 표시, 로그 스트리밍.
+
+**주의:** ReadableStream 사용 시 UTF-8 인코딩을 위해 `TextEncoder.encode()` 필수. async generator가 더 간결하고 타입 안전합니다.
+
+참고: [Streaming Data from Server Functions](https://tanstack.com/start/latest/docs/framework/react/guide/streaming-data-from-server-functions)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/server-validator.md

@@ -0,0 +1,71 @@
+---
+title: Use inputValidator for Type-Safe Server Functions
+impact: HIGH
+impactDescription: runtime type safety with Zod
+tags: server, validation, inputValidator, zod, tanstack-start
+---
+
+## inputValidator로 타입 안전한 Server Functions
+
+`createServerFn`의 `.inputValidator()`로 런타임 입력 검증과 TypeScript 타입 추론을 동시에 확보합니다.
+
+**❌ 잘못된 예시 (검증 없음, 타입 안전하지 않음):**
+
+```typescript
+const createUser = createServerFn({ method: 'POST' })
+  .handler(async (data: any) => {
+    // data가 검증되지 않음 - 런타임 에러 위험
+    return await db.user.create({ data })
+  })
+```
+
+**✅ 올바른 예시 (Zod로 검증 + 타입 추론):**
+
+```typescript
+import { z } from 'zod'
+import { createServerFn } from '@tanstack/react-start'
+
+const UserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email()
+})
+
+const createUser = createServerFn({ method: 'POST' })
+  .inputValidator((d: unknown) => UserSchema.parse(d))
+  .handler(async ({ data }) => {
+    // data는 자동으로 { name: string; email: string } 타입
+    return await db.user.create({ data })
+  })
+
+// 클라이언트에서 호출
+await createUser({ data: { name: 'Alice', email: 'alice@example.com' } })
+```
+
+**중요:** `.inputValidator()`는 반드시 **함수** 형태로 전달해야 합니다. Zod schema를 직접 전달하면 안 됩니다.
+
+```typescript
+// ❌ 잘못됨: schema 직접 전달
+.inputValidator(UserSchema)
+
+// ✅ 올바름: 함수로 감싸서 전달
+.inputValidator((d: unknown) => UserSchema.parse(d))
+```
+
+**FormData 검증:**
+
+```typescript
+const uploadFile = createServerFn({ method: 'POST' })
+  .inputValidator((d: unknown) => {
+    if (!(d instanceof FormData)) throw new Error('Expected FormData')
+    return {
+      name: d.get('name')?.toString() || '',
+      file: d.get('file') as File
+    }
+  })
+  .handler(async ({ data }) => {
+    // data.name, data.file 모두 타입 안전
+    return await saveFile(data.file)
+  })
+```
+
+참고: [Server Functions Guide](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions)