@kood/claude-code 0.2.5 → 0.3.0

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

@@ -1,15 +1,9 @@
 # TanStack Router - Error Handling
 
-errorComponent, notFoundComponent, 에러 경계.
-
-## errorComponent
-
-loader/beforeLoad에서 에러 발생 시 표시.
+<patterns>
 
 ```tsx
-import { createFileRoute, ErrorComponent } from '@tanstack/react-router'
-import type { ErrorComponentProps } from '@tanstack/react-router'
-
+// errorComponent
 export const Route = createFileRoute('/posts/$postId')({
   loader: async ({ params }) => {
     const post = await getPost(params.postId)
@@ -20,170 +14,68 @@ export const Route = createFileRoute('/posts/$postId')({
   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'
+const PostError = ({ error, reset }: ErrorComponentProps) => (
+  <div>
+    <h2>Error loading post</h2>
+    <p>{error.message}</p>
+    <button onClick={reset}>Retry</button>
+  </div>
+)
 
+// notFoundComponent
 export const Route = createFileRoute('/posts/$postId')({
   loader: async ({ params }) => {
     const post = await getPost(params.postId)
-    if (!post) {
-      throw notFound()  // notFoundComponent 렌더링
-    }
+    if (!post) throw notFound({ data: { searchedId: params.postId } })
     return { post }
   },
-  notFoundComponent: PostNotFound,
+  notFoundComponent: ({ data }) => <p>Post {data?.searchedId} not found</p>,
   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'
-
+// Root 404
 export const Route = createRootRoute({
   component: RootLayout,
-  notFoundComponent: GlobalNotFound,
-})
-
-function GlobalNotFound() {
-  return (
+  notFoundComponent: () => (
     <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
+// pendingComponent
 export const Route = createFileRoute('/posts')({
   loader: async () => fetchPosts(),
   pendingComponent: () => <Spinner />,
-  pendingMs: 200,     // 200ms 후에 pending 표시
-  pendingMinMs: 500,  // 최소 500ms 동안 pending 유지 (깜빡임 방지)
+  pendingMs: 200,     // 200ms 후 표시
+  pendingMinMs: 500,  // 최소 500ms 유지 (깜빡임 방지)
   component: PostsPage,
 })
-```
-
-## Catch-all Route
-
-```tsx
-// routes/$.tsx - 모든 매치되지 않는 경로
-import { createFileRoute } from '@tanstack/react-router'
 
+// Catch-all (routes/$.tsx)
 export const Route = createFileRoute('/$')({
-  component: CatchAllPage,
+  component: () => {
+    const { _splat } = Route.useParams()
+    return <div>Page Not Found: /{_splat}</div>
+  },
 })
 
-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) {
-  // 네트워크 에러
+// 에러 타입 구분
+const 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>
-    )
+    return <div><p>Network error</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>
-  )
+  return <div><p>Something went wrong</p><button onClick={reset}>Retry</button></div>
 }
 ```
 
-## 컴포넌트 우선순위
+</patterns>
+
+<priority>
 
 | 우선순위 | 컴포넌트 | 조건 |
 |---------|---------|------|
@@ -192,13 +84,6 @@ function CustomError({ error, reset }: ErrorComponentProps) {
 | 3 | `pendingComponent` | loader 실행 중 (pendingMs 이후) |
 | 4 | `component` | 정상 렌더링 |
 
-## 에러 전파
-
-하위 라우트에서 처리 안 된 에러는 상위로 전파.
+에러 전파: 하위 → 상위 (errorComponent 없으면 부모로 전파)
 
-```
-__root.tsx (errorComponent: GlobalError)
-└── posts.tsx (errorComponent: PostsError)
-    └── $postId.tsx (errorComponent 없음)
-        → 에러 발생 시 posts.tsx의 PostsError로 전파
-```
+</priority>

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

@@ -1,188 +1,44 @@
 # TanStack Router - Hooks
 
-라우터 Hooks 레퍼런스.
-
-## Route-Scoped Hooks
-
-라우트 컴포넌트 내에서 사용. Type-safe.
-
-### Route.useLoaderData()
+<patterns>
 
 ```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 }
+// Route-Scoped (Type-safe)
+const PostPage = () => {
+  const { post } = Route.useLoaderData()      // Loader 반환값
+  const { postId } = Route.useParams()        // Path params
+  const { page, sort } = Route.useSearch()    // Search params
+  const { user } = Route.useRouteContext()    // Route context
   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)
+// Global (Manual type)
+const navigate = useNavigate()
+navigate({ to: '/posts/$postId', params: { postId: '123' } })
 
-```tsx
-import { useParams } from '@tanstack/react-router'
+const postMatch = useMatch({ from: '/posts/$postId', shouldThrow: false })
+if (postMatch) return <span>Post: {postMatch.params.postId}</span>
 
-// 타입 지정 필요
 const { postId } = useParams({ from: '/posts/$postId' })
+const params = useParams({ strict: false })  // 모든 params
 
-// strict: false로 모든 params
-const params = useParams({ strict: false })
-```
-
-### useSearch() (Global)
-
-```tsx
-import { useSearch } from '@tanstack/react-router'
-
-// 타입 지정 필요
 const { page } = useSearch({ from: '/products' })
+const search = useSearch({ strict: false })  // 현재 search
 
-// 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,
-})
+const pathname = useRouterState({ select: state => state.location.pathname })
+const isLoading = useRouterState({ select: state => state.isLoading })
 
-// pending 상태
-const isLoading = useRouterState({
-  select: state => state.isLoading,
-})
+const location = useLocation()
+console.log(location.pathname)  // '/posts/123'
+console.log(location.search)    // { page: 1 }
 ```
 
-### useLocation()
+</patterns>
 
-현재 location 정보.
+<reference>
 
-```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 | 용도 |
-|------|-------|-------------|------|
+| Hook | Scope | Type | 용도 |
+|------|-------|------|------|
 | `Route.useLoaderData()` | Route | Auto | Loader 데이터 |
 | `Route.useParams()` | Route | Auto | Path params |
 | `Route.useSearch()` | Route | Auto | Search params |
@@ -193,3 +49,5 @@ function Component() {
 | `useNavigate()` | Global | Auto | 네비게이션 |
 | `useRouterState()` | Global | Manual | 라우터 상태 |
 | `useLocation()` | Global | Auto | 현재 location |
+
+</reference>

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

@@ -1,6 +1,6 @@
 # TanStack Router
 
-> **Version**: 1.x | Type-safe React Router
+> 1.x | Type-safe React Router
 
 @navigation.md
 @search-params.md
@@ -10,26 +10,18 @@
 
 ---
 
-## Quick Reference
+<quick_reference>
 
 ```tsx
-import { createFileRoute, Link, Outlet } from '@tanstack/react-router'
-
 // 기본 라우트
-export const Route = createFileRoute('/about')({
-  component: AboutPage,
-})
+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 }
-  },
+  loader: async ({ params }) => ({ post: await getPost(params.postId) }),
   component: PostPage,
 })
-
-function PostPage() {
+const PostPage = () => {
   const { post } = Route.useLoaderData()
   return <h1>{post.title}</h1>
 }
@@ -42,16 +34,35 @@ export const Route = createFileRoute('/products')({
   }),
   component: ProductsPage,
 })
-
-function ProductsPage() {
+const ProductsPage = () => {
   const { page, sort } = Route.useSearch()
   return <div>Page {page}, Sort: {sort}</div>
 }
+
+// Root Route
+export const Route = createRootRoute({
+  component: RootLayout,
+  notFoundComponent: () => <div>404</div>,
+})
+const RootLayout = () => (
+  <div>
+    <nav>{/* ... */}</nav>
+    <main><Outlet /></main>
+  </div>
+)
+
+// Navigation
+<Link to="/posts/$postId" params={{ postId: '123' }}>Post</Link>
+<Link to="/products" search={{ page: 1 }}>Products</Link>
+
+const navigate = useNavigate()
+navigate({ to: '/posts/$postId', params: { postId: '123' } })
+navigate({ to: '/products', search: prev => ({ ...prev, page: 2 }) })
 ```
 
----
+</quick_reference>
 
-## 파일 구조
+<structure>
 
 ```
 routes/
@@ -61,84 +72,36 @@ routes/
 ├── posts/
 │   ├── index.tsx       # /posts
 │   └── $postId.tsx     # /posts/:postId
-├── _authed/            # Protected routes (pathless)
+├── _authed/            # Protected (pathless)
 │   ├── dashboard.tsx   # /dashboard
 │   └── settings.tsx    # /settings
 └── $.tsx               # Catch-all (404)
 ```
 
-| 파일명 패턴 | 설명 |
-|------------|------|
+| 파일명 | 경로 |
+|--------|------|
 | `index.tsx` | 디렉토리 루트 |
 | `$param.tsx` | 동적 세그먼트 |
 | `_layout/` | Pathless layout |
 | `$.tsx` | Catch-all |
 
----
-
-## Root Route
+</structure>
 
-```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
+<options>
 
 | 옵션 | 설명 |
 |------|------|
 | `component` | 렌더링할 컴포넌트 |
 | `loader` | 데이터 로드 함수 |
-| `beforeLoad` | 로드 전 실행 (인증 체크 등) |
+| `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 }) })
-```
-
----
+</options>
 
-## Hooks
+<hooks>
 
 | Hook | 용도 |
 |------|------|
@@ -147,4 +110,6 @@ navigate({ to: '/products', search: prev => ({ ...prev, page: 2 }) })
 | `Route.useSearch()` | Search params |
 | `Route.useRouteContext()` | Route context |
 | `useNavigate()` | 프로그래밍 네비게이션 |
-| `useMatch({ from })` | 특정 라우트 매치 정보 |
+| `useMatch({ from })` | 라우트 매치 정보 |
+
+</hooks>