@kood/claude-code 0.2.0 → 0.2.2

package/templates/tanstack-start/docs/library/tanstack-router/error-handling.md

@@ -0,0 +1,204 @@
+# TanStack Router - Error Handling
+
+errorComponent, notFoundComponent, 에러 경계.
+
+## errorComponent
+
+loader/beforeLoad에서 에러 발생 시 표시.
+
+```tsx
+import { createFileRoute, ErrorComponent } from '@tanstack/react-router'
+import type { ErrorComponentProps } from '@tanstack/react-router'
+
+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: PostError,
+  component: PostPage,
+})
+
+function PostError({ error, reset }: ErrorComponentProps) {
+  return (
+    <div>
+      <h2>Error loading post</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Retry</button>
+    </div>
+  )
+}
+```
+
+## notFoundComponent
+
+`notFound()` 호출 시 표시.
+
+```tsx
+import { createFileRoute, notFound } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost(params.postId)
+    if (!post) {
+      throw notFound()  // notFoundComponent 렌더링
+    }
+    return { post }
+  },
+  notFoundComponent: PostNotFound,
+  component: PostPage,
+})
+
+function PostNotFound() {
+  const { postId } = Route.useParams()
+
+  return (
+    <div>
+      <h2>Post not found</h2>
+      <p>Post with ID "{postId}" does not exist.</p>
+    </div>
+  )
+}
+```
+
+### notFound에 데이터 전달
+
+```tsx
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost(params.postId)
+    if (!post) {
+      throw notFound({
+        data: { searchedId: params.postId },
+      })
+    }
+    return { post }
+  },
+  notFoundComponent: ({ data }) => {
+    // data.searchedId 접근 가능
+    return <p>Post {data?.searchedId} not found</p>
+  },
+})
+```
+
+## Root 404 페이지
+
+```tsx
+// routes/__root.tsx
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+  component: RootLayout,
+  notFoundComponent: GlobalNotFound,
+})
+
+function GlobalNotFound() {
+  return (
+    <div>
+      <h1>404</h1>
+      <p>Page not found</p>
+      <Link to="/">Go Home</Link>
+    </div>
+  )
+}
+```
+
+## pendingComponent
+
+loader 실행 중 표시.
+
+```tsx
+export const Route = createFileRoute('/posts')({
+  loader: async () => {
+    await new Promise(r => setTimeout(r, 1000))  // 느린 로딩
+    return { posts: await getPosts() }
+  },
+  pendingComponent: () => <div>Loading posts...</div>,
+  component: PostsPage,
+})
+```
+
+### pendingMs / pendingMinMs
+
+```tsx
+export const Route = createFileRoute('/posts')({
+  loader: async () => fetchPosts(),
+  pendingComponent: () => <Spinner />,
+  pendingMs: 200,     // 200ms 후에 pending 표시
+  pendingMinMs: 500,  // 최소 500ms 동안 pending 유지 (깜빡임 방지)
+  component: PostsPage,
+})
+```
+
+## Catch-all Route
+
+```tsx
+// routes/$.tsx - 모든 매치되지 않는 경로
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/$')({
+  component: CatchAllPage,
+})
+
+function CatchAllPage() {
+  const params = Route.useParams()
+  // params._splat에 전체 경로
+
+  return (
+    <div>
+      <h1>Page Not Found</h1>
+      <p>Path: /{params._splat}</p>
+    </div>
+  )
+}
+```
+
+## 에러 타입 구분
+
+```tsx
+function CustomError({ error, reset }: ErrorComponentProps) {
+  // 네트워크 에러
+  if (error instanceof TypeError && error.message.includes('fetch')) {
+    return (
+      <div>
+        <p>Network error. Check your connection.</p>
+        <button onClick={reset}>Retry</button>
+      </div>
+    )
+  }
+
+  // 인증 에러
+  if (error.message.includes('unauthorized')) {
+    return <Navigate to="/login" />
+  }
+
+  // 기본 에러
+  return (
+    <div>
+      <p>Something went wrong</p>
+      <button onClick={reset}>Retry</button>
+    </div>
+  )
+}
+```
+
+## 컴포넌트 우선순위
+
+| 우선순위 | 컴포넌트 | 조건 |
+|---------|---------|------|
+| 1 | `errorComponent` | loader/beforeLoad에서 Error throw |
+| 2 | `notFoundComponent` | `notFound()` throw |
+| 3 | `pendingComponent` | loader 실행 중 (pendingMs 이후) |
+| 4 | `component` | 정상 렌더링 |
+
+## 에러 전파
+
+하위 라우트에서 처리 안 된 에러는 상위로 전파.
+
+```
+__root.tsx (errorComponent: GlobalError)
+└── posts.tsx (errorComponent: PostsError)
+    └── $postId.tsx (errorComponent 없음)
+        → 에러 발생 시 posts.tsx의 PostsError로 전파
+```

package/templates/tanstack-start/docs/library/tanstack-router/hooks.md

@@ -0,0 +1,195 @@
+# TanStack Router - Hooks
+
+라우터 Hooks 레퍼런스.
+
+## Route-Scoped Hooks
+
+라우트 컴포넌트 내에서 사용. Type-safe.
+
+### Route.useLoaderData()
+
+```tsx
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost(params.postId)
+    return { post }
+  },
+  component: PostPage,
+})
+
+function PostPage() {
+  const { post } = Route.useLoaderData()
+  //      ^? { post: Post }
+  return <h1>{post.title}</h1>
+}
+```
+
+### Route.useParams()
+
+```tsx
+export const Route = createFileRoute('/posts/$postId')({
+  component: PostPage,
+})
+
+function PostPage() {
+  const { postId } = Route.useParams()
+  //      ^? string
+  return <div>Post ID: {postId}</div>
+}
+```
+
+### Route.useSearch()
+
+```tsx
+export const Route = createFileRoute('/products')({
+  validateSearch: z.object({
+    page: z.number().catch(1),
+    sort: z.string().catch('newest'),
+  }),
+  component: ProductsPage,
+})
+
+function ProductsPage() {
+  const { page, sort } = Route.useSearch()
+  //      ^? number, string
+  return <div>Page: {page}, Sort: {sort}</div>
+}
+```
+
+### Route.useRouteContext()
+
+```tsx
+// _authed.tsx에서 beforeLoad로 user 전달 가정
+export const Route = createFileRoute('/_authed/dashboard')({
+  component: DashboardPage,
+})
+
+function DashboardPage() {
+  const { user } = Route.useRouteContext()
+  return <h1>Welcome, {user.name}</h1>
+}
+```
+
+## Global Hooks
+
+어디서든 사용 가능. 타입 안전성 직접 지정.
+
+### useNavigate()
+
+```tsx
+import { useNavigate } from '@tanstack/react-router'
+
+function Component() {
+  const navigate = useNavigate()
+
+  const handleClick = () => {
+    navigate({
+      to: '/posts/$postId',
+      params: { postId: '123' },
+    })
+  }
+}
+```
+
+### useMatch()
+
+특정 라우트 매치 정보 접근.
+
+```tsx
+import { useMatch } from '@tanstack/react-router'
+
+function Breadcrumb() {
+  // 특정 라우트가 현재 매치되면 정보 반환
+  const postMatch = useMatch({
+    from: '/posts/$postId',
+    shouldThrow: false,  // 매치 안 되면 undefined
+  })
+
+  if (postMatch) {
+    return <span>Post: {postMatch.params.postId}</span>
+  }
+
+  return null
+}
+```
+
+### useParams() (Global)
+
+```tsx
+import { useParams } from '@tanstack/react-router'
+
+// 타입 지정 필요
+const { postId } = useParams({ from: '/posts/$postId' })
+
+// strict: false로 모든 params
+const params = useParams({ strict: false })
+```
+
+### useSearch() (Global)
+
+```tsx
+import { useSearch } from '@tanstack/react-router'
+
+// 타입 지정 필요
+const { page } = useSearch({ from: '/products' })
+
+// strict: false로 현재 라우트 search
+const search = useSearch({ strict: false })
+```
+
+### useRouterState()
+
+라우터 전체 상태 접근.
+
+```tsx
+import { useRouterState } from '@tanstack/react-router'
+
+function CurrentPath() {
+  const pathname = useRouterState({
+    select: state => state.location.pathname,
+  })
+
+  return <span>Current: {pathname}</span>
+}
+
+// 전체 location
+const location = useRouterState({
+  select: state => state.location,
+})
+
+// pending 상태
+const isLoading = useRouterState({
+  select: state => state.isLoading,
+})
+```
+
+### useLocation()
+
+현재 location 정보.
+
+```tsx
+import { useLocation } from '@tanstack/react-router'
+
+function Component() {
+  const location = useLocation()
+
+  console.log(location.pathname)  // '/posts/123'
+  console.log(location.search)    // { page: 1 }
+  console.log(location.hash)      // '#section'
+}
+```
+
+## Hook 비교
+
+| Hook | Scope | Type Safety | 용도 |
+|------|-------|-------------|------|
+| `Route.useLoaderData()` | Route | Auto | Loader 데이터 |
+| `Route.useParams()` | Route | Auto | Path params |
+| `Route.useSearch()` | Route | Auto | Search params |
+| `Route.useRouteContext()` | Route | Auto | Route context |
+| `useParams({ from })` | Global | Manual | 다른 라우트 params |
+| `useSearch({ from })` | Global | Manual | 다른 라우트 search |
+| `useMatch({ from })` | Global | Manual | 라우트 매치 정보 |
+| `useNavigate()` | Global | Auto | 네비게이션 |
+| `useRouterState()` | Global | Manual | 라우터 상태 |
+| `useLocation()` | Global | Auto | 현재 location |

package/templates/tanstack-start/docs/library/tanstack-router/index.md

@@ -0,0 +1,150 @@
+# TanStack Router
+
+> **Version**: 1.x | Type-safe React Router
+
+@navigation.md
+@search-params.md
+@route-context.md
+@hooks.md
+@error-handling.md
+
+---
+
+## Quick Reference
+
+```tsx
+import { createFileRoute, Link, Outlet } from '@tanstack/react-router'
+
+// 기본 라우트
+export const Route = createFileRoute('/about')({
+  component: AboutPage,
+})
+
+// Loader + 동적 파라미터
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost(params.postId)
+    return { post }
+  },
+  component: PostPage,
+})
+
+function PostPage() {
+  const { post } = Route.useLoaderData()
+  return <h1>{post.title}</h1>
+}
+
+// Search Params (Zod)
+export const Route = createFileRoute('/products')({
+  validateSearch: z.object({
+    page: z.number().catch(1),
+    sort: z.enum(['newest', 'price']).catch('newest'),
+  }),
+  component: ProductsPage,
+})
+
+function ProductsPage() {
+  const { page, sort } = Route.useSearch()
+  return <div>Page {page}, Sort: {sort}</div>
+}
+```
+
+---
+
+## 파일 구조
+
+```
+routes/
+├── __root.tsx          # Root layout
+├── index.tsx           # /
+├── about.tsx           # /about
+├── posts/
+│   ├── index.tsx       # /posts
+│   └── $postId.tsx     # /posts/:postId
+├── _authed/            # Protected routes (pathless)
+│   ├── dashboard.tsx   # /dashboard
+│   └── settings.tsx    # /settings
+└── $.tsx               # Catch-all (404)
+```
+
+| 파일명 패턴 | 설명 |
+|------------|------|
+| `index.tsx` | 디렉토리 루트 |
+| `$param.tsx` | 동적 세그먼트 |
+| `_layout/` | Pathless layout |
+| `$.tsx` | Catch-all |
+
+---
+
+## Root Route
+
+```tsx
+// routes/__root.tsx
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+  component: RootLayout,
+  notFoundComponent: () => <div>404 Not Found</div>,
+})
+
+function RootLayout() {
+  return (
+    <div>
+      <nav>{/* navigation */}</nav>
+      <main>
+        <Outlet />
+      </main>
+    </div>
+  )
+}
+```
+
+---
+
+## Route Options
+
+| 옵션 | 설명 |
+|------|------|
+| `component` | 렌더링할 컴포넌트 |
+| `loader` | 데이터 로드 함수 |
+| `beforeLoad` | 로드 전 실행 (인증 체크 등) |
+| `validateSearch` | Search params 스키마 |
+| `pendingComponent` | 로딩 중 표시 |
+| `errorComponent` | 에러 발생 시 표시 |
+| `notFoundComponent` | Not found 시 표시 |
+
+---
+
+## Navigation
+
+```tsx
+import { Link, useNavigate } from '@tanstack/react-router'
+
+// Link
+<Link to="/posts/$postId" params={{ postId: '123' }}>
+  Post
+</Link>
+
+// Search params
+<Link to="/products" search={{ page: 1, sort: 'newest' }}>
+  Products
+</Link>
+
+// Programmatic
+const navigate = useNavigate()
+navigate({ to: '/posts/$postId', params: { postId: '123' } })
+navigate({ to: '/products', search: prev => ({ ...prev, page: 2 }) })
+```
+
+---
+
+## Hooks
+
+| Hook | 용도 |
+|------|------|
+| `Route.useLoaderData()` | Loader 반환값 |
+| `Route.useParams()` | Path 파라미터 |
+| `Route.useSearch()` | Search params |
+| `Route.useRouteContext()` | Route context |
+| `useNavigate()` | 프로그래밍 네비게이션 |
+| `useMatch({ from })` | 특정 라우트 매치 정보 |

package/templates/tanstack-start/docs/library/tanstack-router/navigation.md

@@ -0,0 +1,150 @@
+# TanStack Router - Navigation
+
+Link 컴포넌트와 프로그래밍 네비게이션.
+
+## Link 컴포넌트
+
+```tsx
+import { Link } from '@tanstack/react-router'
+
+// 기본
+<Link to="/about">About</Link>
+
+// 동적 파라미터
+<Link to="/posts/$postId" params={{ postId: '123' }}>
+  Post 123
+</Link>
+
+// Search params
+<Link to="/products" search={{ page: 1, sort: 'newest' }}>
+  Products
+</Link>
+
+// Search params 병합
+<Link to="/products" search={prev => ({ ...prev, page: 2 })}>
+  Next Page
+</Link>
+
+// Active 스타일
+<Link
+  to="/about"
+  activeProps={{ className: 'text-blue-500 font-bold' }}
+  inactiveProps={{ className: 'text-gray-500' }}
+>
+  About
+</Link>
+
+// 정확히 일치할 때만 active
+<Link to="/" activeOptions={{ exact: true }}>
+  Home
+</Link>
+```
+
+## Link Props
+
+| Prop | 타입 | 설명 |
+|------|------|------|
+| `to` | string | 목적지 경로 |
+| `params` | object | Path 파라미터 |
+| `search` | object \| function | Search params |
+| `hash` | string | Hash |
+| `replace` | boolean | history replace |
+| `preload` | 'intent' \| 'render' \| 'viewport' | Preload 전략 |
+| `activeProps` | object | Active 시 props |
+| `inactiveProps` | object | Inactive 시 props |
+
+## useNavigate
+
+```tsx
+import { useNavigate } from '@tanstack/react-router'
+
+function Component() {
+  const navigate = useNavigate()
+
+  // 기본
+  const goToAbout = () => {
+    navigate({ to: '/about' })
+  }
+
+  // 동적 파라미터
+  const goToPost = (postId: string) => {
+    navigate({ to: '/posts/$postId', params: { postId } })
+  }
+
+  // Search params
+  const updateSearch = () => {
+    navigate({
+      to: '/products',
+      search: prev => ({ ...prev, page: 2 }),
+    })
+  }
+
+  // Replace (뒤로가기 안 됨)
+  const replaceRoute = () => {
+    navigate({ to: '/login', replace: true })
+  }
+
+  // 상대 경로
+  const goUp = () => {
+    navigate({ to: '..' })
+  }
+
+  return (
+    <button onClick={goToAbout}>Go to About</button>
+  )
+}
+```
+
+## navigate 옵션
+
+| 옵션 | 타입 | 설명 |
+|------|------|------|
+| `to` | string | 목적지 경로 |
+| `params` | object | Path 파라미터 |
+| `search` | object \| function | Search params |
+| `hash` | string | Hash |
+| `replace` | boolean | history.replace 사용 |
+| `resetScroll` | boolean | 스크롤 리셋 |
+
+## Preloading
+
+```tsx
+// hover 시 preload
+<Link to="/posts" preload="intent">
+  Posts
+</Link>
+
+// 렌더링 시 preload
+<Link to="/dashboard" preload="render">
+  Dashboard
+</Link>
+
+// viewport 진입 시 preload
+<Link to="/products" preload="viewport">
+  Products
+</Link>
+```
+
+## 조건부 네비게이션
+
+```tsx
+function SubmitButton() {
+  const navigate = useNavigate()
+  const [isPending, startTransition] = useTransition()
+
+  const handleSubmit = async () => {
+    const result = await submitForm()
+    if (result.success) {
+      startTransition(() => {
+        navigate({ to: '/success' })
+      })
+    }
+  }
+
+  return (
+    <button onClick={handleSubmit} disabled={isPending}>
+      Submit
+    </button>
+  )
+}
+```