@kood/claude-code 0.6.6 → 0.7.0

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/routing-pending-component.md

@@ -0,0 +1,110 @@
+---
+title: Use pendingComponent for Route Loading States
+impact: MEDIUM
+impactDescription: eliminates layout shift during navigation
+tags: routing, pendingComponent, loading, UX, transitions
+---
+
+## pendingComponent로 라우트 로딩 상태 처리
+
+`pendingComponent`는 loader가 완료되기 전 보여주는 로딩 UI입니다. `pendingMs`/`pendingMinMs`로 플리커 없는 로딩 경험을 구현합니다.
+
+**❌ 잘못된 예시 (로딩 상태 없음):**
+
+```tsx
+export const Route = createFileRoute('/tasks')({
+  loader: async () => {
+    const tasks = await fetchTasks()  // 2초 소요
+    return { tasks }
+  },
+  component: TasksPage,
+  // 로딩 UI 없음 → 사용자가 2초간 빈 화면 봄
+})
+```
+
+**✅ 올바른 예시 (pendingComponent + 타이밍 설정):**
+
+```tsx
+export const Route = createFileRoute('/tasks')({
+  loader: async () => {
+    return { tasks: await fetchTasks() }
+  },
+  pendingComponent: () => (
+    <div className="p-4">
+      <div className="animate-pulse space-y-3">
+        <div className="h-8 bg-gray-200 rounded w-1/3" />
+        <div className="h-4 bg-gray-200 rounded" />
+        <div className="h-4 bg-gray-200 rounded" />
+      </div>
+    </div>
+  ),
+  pendingMs: 150,     // 150ms 후에도 loader 미완료 시 로딩 UI 표시
+  pendingMinMs: 200,  // 로딩 UI 최소 200ms 표시 (플리커 방지)
+  component: TasksPage,
+})
+```
+
+**타이밍 동작:**
+
+```
+Time 0ms:      네비게이션 시작
+Time 150ms:    pendingMs 경과 → loader 미완료면 pendingComponent 표시
+               loader 완료면 즉시 컴포넌트 렌더링 (로딩 UI 없음)
+
+pendingComponent 표시 후:
+  loader 완료 시 → 최소 200ms(pendingMinMs) 후 컴포넌트 전환
+  (짧은 플리커 방지)
+```
+
+**Router 레벨 기본값:**
+
+```tsx
+const router = createRouter({
+  routeTree,
+  defaultPendingComponent: () => <GlobalSpinner />,
+  defaultPendingMs: 150,
+  defaultPendingMinMs: 200,
+})
+```
+
+**pendingComponent vs Suspense:**
+
+| 항목 | pendingComponent | Suspense |
+|------|-----------------|----------|
+| 대상 | 라우트 네비게이션 | 컴포넌트 내 비동기 |
+| 트리거 | loader 미완료 | Promise throw |
+| 타이밍 제어 | pendingMs/pendingMinMs | 없음 |
+| 사용 시점 | 페이지 전환 | deferred data, lazy 컴포넌트 |
+
+**조합 패턴 (pendingComponent + Suspense):**
+
+```tsx
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost(params.postId)             // 빠른 데이터
+    const deferredComments = getComments(params.postId)    // 느린 데이터
+    return { post, deferredComments }
+  },
+  // 페이지 전환 시 로딩 UI (post 로딩 중)
+  pendingComponent: () => <PostSkeleton />,
+  pendingMs: 150,
+  component: PostPage,
+})
+
+function PostPage() {
+  const { post, deferredComments } = Route.useLoaderData()
+  return (
+    <div>
+      <PostContent post={post} />
+      {/* 댓글은 별도 Suspense (이미 post는 로드됨) */}
+      <Suspense fallback={<CommentsSkeleton />}>
+        <Await promise={deferredComments}>
+          {(comments) => <Comments comments={comments} />}
+        </Await>
+      </Suspense>
+    </div>
+  )
+}
+```
+
+참고: [Pending Component](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#pending-component)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/routing-preload-strategy.md

@@ -0,0 +1,91 @@
+---
+title: Preload Routes on User Intent for Instant Navigation
+impact: MEDIUM-HIGH
+impactDescription: eliminates perceived loading time on navigation
+tags: routing, preload, performance, link, UX
+---
+
+## 사용자 의도 기반 라우트 프리로딩
+
+`preload="intent"`로 hover/touch 시 라우트 데이터를 미리 로드하여 즉각적인 네비게이션을 구현합니다.
+
+**❌ 잘못된 예시 (프리로딩 없음):**
+
+```tsx
+// 클릭 후 loader 실행 → 사용자 대기
+<Link to="/posts/$postId" params={{ postId: '123' }}>
+  View Post
+</Link>
+```
+
+**✅ 올바른 예시 (intent 프리로딩):**
+
+```tsx
+// hover 시 미리 loader 실행 → 클릭 시 즉시 렌더링
+<Link
+  to="/posts/$postId"
+  params={{ postId: '123' }}
+  preload="intent"
+>
+  View Post
+</Link>
+```
+
+**Router 레벨 기본값 설정:**
+
+```tsx
+const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent',          // 전역 기본값
+  defaultPreloadDelay: 50,           // hover 후 50ms 대기
+  defaultPreloadStaleTime: 30_000,   // 프리로드 데이터 30초간 fresh
+})
+```
+
+**프리로딩 모드:**
+
+| 모드 | 트리거 | 사용 시점 |
+|------|--------|---------|
+| `'intent'` | hover/touch 50ms 후 | 일반적인 네비게이션 링크 (권장) |
+| `'viewport'` | 뷰포트 진입 시 | 목록 페이지, 무한 스크롤 |
+| `'render'` | 컴포넌트 마운트 시 | 확실히 이동할 링크 |
+| `false` | 비활성 | 인증/외부 링크 |
+
+**Link별 오버라이드:**
+
+```tsx
+// 목록 아이템은 viewport 프리로딩
+{posts.map(post => (
+  <Link
+    key={post.id}
+    to="/posts/$postId"
+    params={{ postId: post.id }}
+    preload="viewport"
+  >
+    {post.title}
+  </Link>
+))}
+
+// 특정 링크는 프리로딩 비활성
+<Link to="/settings" preload={false}>
+  Settings
+</Link>
+```
+
+**프로그래밍 방식 프리로딩:**
+
+```tsx
+const router = useRouter()
+
+// 검색 결과 hover 시 수동 프리로드
+const handleMouseEnter = (postId: string) => {
+  router.preloadRoute({
+    to: '/posts/$postId',
+    params: { postId },
+  })
+}
+```
+
+**캐싱:** 프리로드된 데이터는 기본 30초(`defaultPreloadStaleTime`) 동안 fresh 상태로 유지됩니다.
+
+참고: [Preloading Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/routing-router-context.md

@@ -0,0 +1,120 @@
+---
+title: Use Router Context for Dependency Injection
+impact: MEDIUM-HIGH
+impactDescription: enables type-safe shared state across all routes
+tags: routing, context, createRootRouteWithContext, dependency-injection
+---
+
+## Router Context로 의존성 주입
+
+`createRootRouteWithContext`로 QueryClient, 인증 상태 등을 타입 안전하게 모든 라우트에 전달합니다.
+
+**❌ 잘못된 예시 (전역 변수/import):**
+
+```tsx
+// 전역 import → 테스트 어려움, 타입 안전성 없음
+import { queryClient } from '../lib/queryClient'
+import { getAuth } from '../lib/auth'
+
+export const Route = createFileRoute('/dashboard')({
+  loader: async () => {
+    const user = await getAuth()  // 타입 추론 불가
+    return await queryClient.fetchQuery(...)
+  },
+})
+```
+
+**✅ 올바른 예시 (createRootRouteWithContext):**
+
+```tsx
+// 1. Context 인터페이스 정의
+interface RouterContext {
+  queryClient: QueryClient
+  auth: { user: User | null }
+}
+
+// 2. Root route에 context 타입 바인딩
+// src/routes/__root.tsx
+import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: () => <Outlet />,
+})
+
+// 3. Router 생성 시 context 값 전달
+// src/router.tsx
+const router = createRouter({
+  routeTree,
+  context: {
+    queryClient: new QueryClient(),
+    auth: { user: null },
+  },
+})
+
+// 4. 하위 라우트에서 타입 안전하게 접근
+export const Route = createFileRoute('/dashboard')({
+  beforeLoad: async ({ context }) => {
+    // context.queryClient: QueryClient ✅ 완전한 타입 추론
+    // context.auth: { user: User | null } ✅
+    if (!context.auth.user) {
+      throw redirect({ to: '/login' })
+    }
+  },
+  loader: async ({ context }) => {
+    return context.queryClient.ensureQueryData({
+      queryKey: ['dashboard'],
+      queryFn: fetchDashboard,
+    })
+  },
+})
+```
+
+**beforeLoad에서 context 확장:**
+
+```tsx
+// 부모 라우트에서 context 확장 → 자식 라우트에서 접근
+export const Route = createFileRoute('/admin')({
+  beforeLoad: async ({ context }) => {
+    const permissions = await fetchPermissions(context.auth.user!.id)
+    return { permissions }  // context에 병합됨
+  },
+})
+
+// 자식 라우트
+export const Route = createFileRoute('/admin/users')({
+  beforeLoad: async ({ context }) => {
+    // context.permissions 접근 가능 (부모에서 추가됨)
+    if (!context.permissions.includes('manage_users')) {
+      throw redirect({ to: '/admin' })
+    }
+  },
+})
+```
+
+**컴포넌트에서 context 접근:**
+
+```tsx
+function Dashboard() {
+  // useRouteContext로 접근
+  const { queryClient, auth } = Route.useRouteContext()
+
+  // 또는 getRouteApi 사용 (코드 스플릿)
+  const routeApi = getRouteApi('/dashboard')
+  const context = routeApi.useRouteContext()
+}
+```
+
+**useRouterState (라우터 전역 상태):**
+
+```tsx
+// 라우터 상태 반응형 구독
+const status = useRouterState({ select: (s) => s.status })
+// 'idle' | 'pending' → 전역 로딩 인디케이터에 사용
+
+const location = useRouterState({ select: (s) => s.location })
+// 현재 URL 정보
+
+// ⚠️ useRouter().state는 반응형이 아님 → useRouterState 사용
+```
+
+참고: [Router Context](https://tanstack.com/router/latest/docs/framework/react/guide/router-context)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/routing-search-params.md

@@ -0,0 +1,114 @@
+---
+title: Validate Search Params with Zod for Type Safety
+impact: HIGH
+impactDescription: prevents invalid URL state and runtime errors
+tags: routing, search-params, useSearch, zod, validation, type-safety
+---
+
+## Zod로 Search Params 타입 안전하게 검증
+
+TanStack Router의 `validateSearch`로 URL search params를 스키마 기반으로 검증하고, `useSearch`로 타입 안전하게 접근합니다.
+
+**❌ 잘못된 예시 (타입 없는 search params):**
+
+```tsx
+function PostsPage() {
+  const searchParams = new URLSearchParams(window.location.search)
+  const page = Number(searchParams.get('page')) || 1  // 타입 안전성 없음
+  const sort = searchParams.get('sort') ?? 'date'     // 유효성 검증 없음
+}
+```
+
+**✅ 올바른 예시 (Zod 스키마 + validateSearch):**
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+import { zodValidator, fallback } from '@tanstack/zod-adapter'
+
+const postsSearchSchema = z.object({
+  page: fallback(z.number().int().positive(), 1),
+  sort: fallback(z.enum(['date', 'title', 'author']), 'date'),
+  q: fallback(z.string().optional(), undefined),
+  limit: fallback(z.number().int().min(1).max(100), 20),
+})
+
+export const Route = createFileRoute('/posts')({
+  validateSearch: zodValidator(postsSearchSchema),
+  component: PostsPage,
+})
+
+function PostsPage() {
+  // 모든 타입이 스키마에서 자동 추론
+  const { page, sort, q, limit } = Route.useSearch()
+
+  return <div>Page {page}, sorted by {sort}</div>
+}
+```
+
+**useSearch에서 select로 리렌더 최적화:**
+
+```tsx
+// ❌ 전체 search 구독 - 아무 param 변경 시 리렌더
+function Pagination() {
+  const { page, sort, q, limit } = Route.useSearch()
+  return <div>Page {page}</div>  // page만 사용하는데 전체 리렌더
+}
+
+// ✅ select로 필요한 값만 구독
+function Pagination() {
+  const page = useSearch({
+    from: '/posts',
+    select: (search) => search.page,
+  })
+  return <div>Page {page}</div>  // page 변경 시에만 리렌더
+}
+```
+
+**네비게이션에서 search params 업데이트:**
+
+```tsx
+function PostsFilter() {
+  const navigate = useNavigate({ from: '/posts' })
+  const { sort, q } = Route.useSearch()
+
+  const handleSortChange = (newSort: string) => {
+    navigate({
+      search: (prev) => ({ ...prev, sort: newSort, page: 1 }),
+    })
+  }
+
+  const clearFilters = () => {
+    navigate({
+      search: { page: 1, sort: 'date', limit: 20 },  // 전체 초기화
+    })
+  }
+
+  return (
+    <div>
+      <select value={sort} onChange={(e) => handleSortChange(e.target.value)}>
+        <option value="date">Date</option>
+        <option value="title">Title</option>
+      </select>
+      <button onClick={clearFilters}>Clear</button>
+    </div>
+  )
+}
+```
+
+**복잡한 스키마 패턴:**
+
+```tsx
+const filterSchema = z.object({
+  search: z.string().trim().optional(),
+  page: z.coerce.number().int().min(1).default(1),
+  sort: z.enum(['name', 'date', 'popularity']).default('date'),
+  order: z.enum(['asc', 'desc']).default('asc'),
+  inStock: z.coerce.boolean().default(true),
+  categories: z.array(z.string()).default([]),
+})
+```
+
+**주의:** `@tanstack/zod-adapter`는 별도 패키지입니다. Valibot 사용 시 `@tanstack/valibot-adapter`.
+
+참고: [Search Params Guide](https://tanstack.com/router/latest/docs/framework/react/guide/search-params)

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

@@ -64,4 +64,4 @@ function PostPage() {
 
 페이지가 3초 대신 50ms에 렌더링됩니다. 댓글은 준비되면 스트리밍. 다음에 사용: 분석, 추천, 사용자 활동, 소셜 기능.
 
-참고: [TanStack Router Deferred Data Loading](https://tanstack.com/router/v1/docs/framework/react/guide/deferred-data-loading)
+참고: [TanStack Router Deferred Data Loading](https://tanstack.com/router/latest/docs/framework/react/guide/deferred-data-loading)

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)