@kood/claude-code 0.6.5 → 0.6.7

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/routing-nested-layouts.md

@@ -0,0 +1,155 @@
+---
+title: Use Outlet and Pathless Layouts for Nested UI
+impact: HIGH
+impactDescription: enables shared UI structure without prop drilling
+tags: routing, outlet, layouts, createRootRoute, nesting
+---
+
+## Outlet과 Pathless Layout으로 중첩 UI 구현
+
+`<Outlet />`으로 하위 라우트를 렌더링하고, pathless layout(`_prefix`)으로 URL 변경 없이 공유 UI를 적용합니다.
+
+**❌ 잘못된 예시 (레이아웃 중복):**
+
+```tsx
+// routes/dashboard/overview.tsx
+function OverviewPage() {
+  return (
+    <div className="dashboard">
+      <Sidebar />       {/* 중복 */}
+      <main><Overview /></main>
+    </div>
+  )
+}
+
+// routes/dashboard/analytics.tsx
+function AnalyticsPage() {
+  return (
+    <div className="dashboard">
+      <Sidebar />       {/* 중복 */}
+      <main><Analytics /></main>
+    </div>
+  )
+}
+```
+
+**✅ 올바른 예시 (Outlet으로 레이아웃 공유):**
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+  component: () => (
+    <div>
+      <Header />
+      <Outlet />   {/* 하위 라우트가 여기에 렌더링 */}
+      <Footer />
+    </div>
+  ),
+})
+
+// src/routes/dashboard.tsx - 레이아웃 라우트
+export const Route = createFileRoute('/dashboard')({
+  component: DashboardLayout,
+})
+
+function DashboardLayout() {
+  return (
+    <div className="dashboard">
+      <Sidebar />
+      <main>
+        <Outlet />  {/* dashboard/overview, dashboard/analytics 렌더링 */}
+      </main>
+    </div>
+  )
+}
+
+// src/routes/dashboard/overview.tsx
+export const Route = createFileRoute('/dashboard/overview')({
+  component: () => <Overview />,  // DashboardLayout 안에 렌더링
+})
+
+// src/routes/dashboard/analytics.tsx
+export const Route = createFileRoute('/dashboard/analytics')({
+  component: () => <Analytics />,
+})
+```
+
+**Pathless Layout (URL 없는 레이아웃):**
+
+```
+src/routes/
+├── _public.tsx              ← /없음 (pathless, navbar+footer만)
+├── _public/
+│   ├── index.tsx            → /
+│   ├── about.tsx            → /about
+│   └── pricing.tsx          → /pricing
+├── _dashboard.tsx           ← /없음 (pathless, sidebar 레이아웃)
+└── _dashboard/
+    ├── overview.tsx         → /overview
+    ├── analytics.tsx        → /analytics
+    └── settings.tsx         → /settings
+```
+
+```tsx
+// src/routes/_dashboard.tsx
+export const Route = createFileRoute('/_dashboard')({
+  component: () => (
+    <div className="flex">
+      <Sidebar />
+      <main className="flex-1">
+        <Outlet />
+      </main>
+    </div>
+  ),
+})
+
+// src/routes/_dashboard/overview.tsx
+export const Route = createFileRoute('/_dashboard/overview')({
+  component: () => <h1>Overview</h1>,  // URL: /overview
+})
+```
+
+**Route Group vs Pathless Layout:**
+
+| 패턴 | 문법 | URL 영향 | 레이아웃 |
+|------|------|---------|---------|
+| **Route Group** | `(groupName)/` | 없음 | ❌ 불가 |
+| **Pathless Layout** | `_layoutName.tsx` | 없음 | ✅ 가능 |
+
+- Route Group `(public)/`: 파일 정리용, 레이아웃 없음
+- Pathless Layout `_public.tsx`: 공유 UI 래핑 가능
+
+**createRootRouteWithContext:**
+
+```tsx
+// 타입 안전한 전역 context
+interface RouterContext {
+  queryClient: QueryClient
+  auth: AuthState
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: () => <Outlet />,
+})
+
+// 하위 라우트에서 context 접근
+export const Route = createFileRoute('/dashboard')({
+  beforeLoad: ({ context }) => {
+    // context.queryClient, context.auth 타입 안전
+  },
+})
+```
+
+**component 생략 시 자동 Outlet:**
+
+```tsx
+// component를 지정하지 않으면 자동으로 <Outlet /> 렌더링
+export const Route = createFileRoute('/app')({
+  // component 생략 → Outlet 자동 렌더링
+  beforeLoad: async ({ context }) => { /* ... */ },
+})
+```
+
+참고: [Outlets Guide](https://tanstack.com/router/latest/docs/framework/react/guide/outlets), [Route Trees](https://tanstack.com/router/latest/docs/framework/react/guide/route-trees)

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

@@ -0,0 +1,89 @@
+---
+title: Use Type-Safe Path Params with useParams and getRouteApi
+impact: HIGH
+impactDescription: ensures correct param types across code-split components
+tags: routing, path-params, useParams, getRouteApi, type-safety
+---
+
+## useParams와 getRouteApi로 타입 안전한 Path Params
+
+TanStack Router의 `useParams`와 `getRouteApi`로 동적 라우트 파라미터를 타입 안전하게 접근합니다.
+
+**❌ 잘못된 예시 (타입 안전성 없음):**
+
+```tsx
+// strict: false는 타입 추론 약화
+function PostDetail() {
+  const params = useParams({ strict: false })
+  const postId = params.postId  // any 타입
+}
+```
+
+**✅ 올바른 예시 (Route 바인딩):**
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    // params.postId는 string 타입으로 자동 추론
+    return { post: await getPost(params.postId) }
+  },
+  component: PostDetail,
+})
+
+function PostDetail() {
+  // Route에 바인딩된 useParams - 완전한 타입 추론
+  const { postId } = Route.useParams()
+  const { post } = Route.useLoaderData()
+
+  return <div>{post.title}</div>
+}
+```
+
+**✅ 올바른 예시 (getRouteApi - 코드 스플릿 컴포넌트):**
+
+```tsx
+// components/PostDetail.tsx (별도 파일)
+import { getRouteApi } from '@tanstack/react-router'
+
+// Route import 없이 타입 안전하게 접근
+const routeApi = getRouteApi('/posts/$postId')
+
+export function PostDetail() {
+  const { postId } = routeApi.useParams()
+  const { post } = routeApi.useLoaderData()
+  const search = routeApi.useSearch()
+  const context = routeApi.useRouteContext()
+
+  return <div>{post.title}</div>
+}
+```
+
+**select로 리렌더 최적화:**
+
+```tsx
+// postId만 변경 시 리렌더
+const postId = useParams({
+  from: '/posts/$postId',
+  select: (params) => params.postId,
+})
+```
+
+**from으로 타입 컨텍스트 지정:**
+
+```tsx
+// 다른 라우트의 params 접근
+const { postId } = useParams({ from: '/posts/$postId' })
+
+// 현재 라우트 컨텍스트에서 접근 (Route 바인딩)
+const { postId } = Route.useParams()
+```
+
+**타입 안전성 순위:**
+1. `Route.useParams()` - 라우트에 직접 바인딩, 최고 타입 안전성
+2. `getRouteApi('/path').useParams()` - 코드 스플릿 시 사용, 순환 의존성 방지
+3. `useParams({ from: '/path' })` - from으로 타입 컨텍스트 지정
+4. `useParams({ strict: false })` - 전역 접근, 타입 약화 (비권장)
+
+참고: [Path Params Guide](https://tanstack.com/router/latest/docs/framework/react/guide/path-params), [getRouteApi](https://tanstack.com/router/latest/docs/framework/react/api/router/getRouteApiFunction)

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)