@kood/claude-code 0.6.5 → 0.6.7

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

@@ -0,0 +1,79 @@
+---
+title: Use Route-Level Error Boundaries
+impact: HIGH
+impactDescription: graceful error recovery per route
+tags: server, error-handling, error-boundary, tanstack-router
+---
+
+## 라우트 레벨 에러 바운더리
+
+TanStack Router는 라우트별 `errorComponent`를 지원합니다. 전역 에러 페이지 대신 라우트 단위 에러 처리로 사용자 경험을 개선하세요.
+
+**❌ 잘못된 예시 (에러 처리 없음):**
+
+```typescript
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost(params.postId)
+    return { post } // post가 null이면 런타임 에러
+  },
+  component: PostPage
+})
+
+function PostPage() {
+  const { post } = Route.useLoaderData()
+  return <div>{post.title}</div> // 💥 Cannot read property 'title' of null
+}
+```
+
+**✅ 올바른 예시 (라우트별 에러 처리):**
+
+```typescript
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost(params.postId)
+    if (!post) throw new Error('Post not found')
+    return { post }
+  },
+  errorComponent: ({ error, reset }) => (
+    <div>
+      <h2>오류가 발생했습니다</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>다시 시도</button>
+    </div>
+  ),
+  component: PostPage
+})
+```
+
+**전역 기본 에러 컴포넌트 설정:**
+
+```typescript
+import { createRouter } from '@tanstack/react-router'
+
+const router = createRouter({
+  routeTree,
+  defaultErrorComponent: ({ error, reset }) => (
+    <div>
+      <h1>예기치 못한 오류</h1>
+      <p>{error.message}</p>
+      <button onClick={reset}>재시도</button>
+    </div>
+  )
+})
+```
+
+**notFoundComponent로 404 처리:**
+
+```typescript
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost(params.postId)
+    if (!post) throw notFound()
+    return { post }
+  },
+  notFoundComponent: () => <div>게시글을 찾을 수 없습니다</div>
+})
+```
+
+**원칙:** loader에서 예외를 명시적으로 throw하고, errorComponent/notFoundComponent로 처리합니다. TanStack Router가 자동으로 Suspense와 ErrorBoundary를 래핑합니다.

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

@@ -0,0 +1,85 @@
+---
+title: Use Middleware for Cross-Cutting Concerns
+impact: HIGH
+impactDescription: centralizes auth, logging, validation
+tags: server, middleware, createMiddleware, authentication, tanstack-start
+---
+
+## 크로스 커팅 관심사에 Middleware 사용
+
+`createMiddleware()`로 인증, 로깅, 에러 처리 등 공통 로직을 중앙화합니다. 각 Server Function에 반복 코드를 작성하지 마세요.
+
+**❌ 잘못된 예시 (모든 Server Function에 인증 로직 반복):**
+
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+
+const getTodos = createServerFn().handler(async () => {
+  const session = await getSession()
+  if (!session?.user) throw new Error('Unauthorized')
+  return await db.todo.findMany({ where: { userId: session.user.id } })
+})
+
+const createTodo = createServerFn({ method: 'POST' })
+  .handler(async (data) => {
+    const session = await getSession()
+    if (!session?.user) throw new Error('Unauthorized')
+    return await db.todo.create({ data: { ...data, userId: session.user.id } })
+  })
+```
+
+**✅ 올바른 예시 (Middleware로 인증 중앙화):**
+
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+import { createMiddleware } from '@tanstack/react-start'
+
+// 인증 미들웨어 정의 (재사용 가능)
+const authMiddleware = createMiddleware()
+  .server(async ({ next }) => {
+    const session = await getSession()
+    if (!session?.user) {
+      throw redirect({ to: '/login' })
+    }
+    return next({ context: { user: session.user } })
+  })
+
+// Server Functions에 미들웨어 적용
+const getTodos = createServerFn()
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    return await db.todo.findMany({ where: { userId: context.user.id } })
+  })
+
+const createTodo = createServerFn({ method: 'POST' })
+  .middleware([authMiddleware])
+  .inputValidator((d: unknown) => TodoSchema.parse(d))
+  .handler(async ({ data, context }) => {
+    return await db.todo.create({ data: { ...data, userId: context.user.id } })
+  })
+```
+
+**미들웨어 체이닝:**
+
+```typescript
+const loggingMiddleware = createMiddleware()
+  .server(async ({ next }) => {
+    const start = Date.now()
+    const result = await next()
+    console.log(`Duration: ${Date.now() - start}ms`)
+    return result
+  })
+
+// 여러 미들웨어 조합 (배열 순서대로 실행)
+const protectedAction = createServerFn({ method: 'POST' })
+  .middleware([loggingMiddleware, authMiddleware])
+  .handler(async ({ context }) => { /* ... */ })
+```
+
+**실행 순서:** inputValidator → middleware (배열 순서) → handler
+
+**주의사항:**
+- 미들웨어 코드가 클라이언트 번들에 포함될 수 있으므로, DB 연결/API 키 등 민감 정보는 handler 내에서만 사용
+- `redirect()` 사용 시 직렬화 에러가 발생할 수 있으므로 `throw redirect()` 패턴 사용
+
+참고: [Middleware Guide](https://tanstack.com/start/latest/docs/framework/react/guide/middleware)

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)