@kood/claude-code 0.2.1 → 0.2.2

package/templates/tanstack-start/docs/library/tanstack-router/route-context.md

@@ -0,0 +1,203 @@
+# TanStack Router - Route Context
+
+beforeLoad, context, protected routes 구현.
+
+## beforeLoad
+
+라우트 로드 전 실행. 인증 체크, 리다이렉트, context 추가.
+
+```tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/dashboard')({
+  beforeLoad: async ({ context, location }) => {
+    // context에서 인증 상태 확인
+    if (!context.auth.isAuthenticated) {
+      throw redirect({
+        to: '/login',
+        search: { redirect: location.href },
+      })
+    }
+
+    // 추가 context 반환 (loader에서 사용 가능)
+    return {
+      userPermissions: await fetchPermissions(context.auth.user.id),
+    }
+  },
+  loader: async ({ context }) => {
+    // beforeLoad에서 반환한 context 사용
+    return fetchDashboardData(context.userPermissions)
+  },
+  component: DashboardPage,
+})
+```
+
+## Protected Routes (Layout)
+
+pathless layout으로 보호된 라우트 그룹 생성.
+
+### _authed.tsx (Layout)
+
+```tsx
+// routes/_authed.tsx
+import { createFileRoute, redirect, Outlet } from '@tanstack/react-router'
+import { getCurrentUser } from '@/functions/auth'
+
+export const Route = createFileRoute('/_authed')({
+  beforeLoad: async ({ location }) => {
+    const user = await getCurrentUser()
+
+    if (!user) {
+      throw redirect({
+        to: '/login',
+        search: { redirect: location.href },
+      })
+    }
+
+    // 하위 라우트에서 사용할 context
+    return { user }
+  },
+  component: () => <Outlet />,
+})
+```
+
+### _authed/dashboard.tsx
+
+```tsx
+// routes/_authed/dashboard.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authed/dashboard')({
+  component: DashboardPage,
+})
+
+function DashboardPage() {
+  // _authed에서 전달된 context
+  const { user } = Route.useRouteContext()
+
+  return (
+    <div>
+      <h1>Welcome, {user.name}!</h1>
+    </div>
+  )
+}
+```
+
+### 구조
+
+```
+routes/
+├── _authed.tsx           # Protected layout (beforeLoad에서 인증 체크)
+├── _authed/
+│   ├── dashboard.tsx     # /dashboard (protected)
+│   ├── settings.tsx      # /settings (protected)
+│   └── profile.tsx       # /profile (protected)
+├── login.tsx             # /login (public)
+└── index.tsx             # / (public)
+```
+
+## Root Context
+
+전역 context 설정 (QueryClient, Auth 등).
+
+### __root.tsx
+
+```tsx
+// routes/__root.tsx
+import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
+import type { QueryClient } from '@tanstack/react-query'
+
+interface RouterContext {
+  queryClient: QueryClient
+  auth: {
+    isAuthenticated: boolean
+    user: { id: string; name: string } | null
+  }
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: RootLayout,
+})
+
+function RootLayout() {
+  return (
+    <div>
+      <Outlet />
+    </div>
+  )
+}
+```
+
+### Router 생성
+
+```tsx
+// app/router.tsx
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+import { queryClient } from './query-client'
+
+export const router = createRouter({
+  routeTree,
+  context: {
+    queryClient,
+    auth: {
+      isAuthenticated: false,
+      user: null,
+    },
+  },
+})
+```
+
+## redirect
+
+```tsx
+import { redirect } from '@tanstack/react-router'
+
+// 기본 리다이렉트
+throw redirect({ to: '/login' })
+
+// Search params 포함
+throw redirect({
+  to: '/login',
+  search: { redirect: '/dashboard' },
+})
+
+// 동적 파라미터
+throw redirect({
+  to: '/posts/$postId',
+  params: { postId: '123' },
+})
+
+// replace (뒤로가기 X)
+throw redirect({
+  to: '/home',
+  replace: true,
+})
+```
+
+## Context 사용 위치
+
+| 위치 | 접근 방법 |
+|------|----------|
+| beforeLoad | `{ context }` 파라미터 |
+| loader | `{ context }` 파라미터 |
+| component | `Route.useRouteContext()` |
+
+```tsx
+export const Route = createFileRoute('/example')({
+  beforeLoad: ({ context }) => {
+    console.log(context.auth)
+    return { extra: 'data' }
+  },
+  loader: ({ context }) => {
+    // beforeLoad 반환값도 포함됨
+    console.log(context.extra)
+  },
+  component: ExamplePage,
+})
+
+function ExamplePage() {
+  const context = Route.useRouteContext()
+  // context.auth, context.extra 모두 접근 가능
+}
+```

package/templates/tanstack-start/docs/library/tanstack-router/search-params.md

@@ -0,0 +1,213 @@
+# TanStack Router - Search Params
+
+Type-safe URL search params with Zod validation.
+
+## 기본 사용
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+
+// 스키마 정의
+const productSearchSchema = z.object({
+  page: z.number().catch(1),
+  filter: z.string().catch(''),
+  sort: z.enum(['newest', 'oldest', 'price']).catch('newest'),
+})
+
+type ProductSearch = z.infer<typeof productSearchSchema>
+
+// 라우트에 적용
+export const Route = createFileRoute('/products')({
+  validateSearch: productSearchSchema,
+  component: ProductsPage,
+})
+
+// 컴포넌트에서 사용
+function ProductsPage() {
+  const { page, filter, sort } = Route.useSearch()
+
+  return (
+    <div>
+      <p>Page: {page}</p>
+      <p>Filter: {filter}</p>
+      <p>Sort: {sort}</p>
+    </div>
+  )
+}
+```
+
+## Zod 스키마 패턴
+
+```tsx
+import { z } from 'zod'
+
+// 기본값 (.catch)
+const schema = z.object({
+  page: z.number().catch(1),            // 파싱 실패 시 1
+  search: z.string().optional(),        // undefined 허용
+  tab: z.enum(['all', 'active']).catch('all'),
+})
+
+// 복잡한 타입
+const advancedSchema = z.object({
+  // 배열
+  tags: z.array(z.string()).catch([]),
+
+  // 날짜
+  from: z.string().date().optional(),
+  to: z.string().date().optional(),
+
+  // 숫자 범위
+  minPrice: z.number().min(0).catch(0),
+  maxPrice: z.number().max(10000).catch(10000),
+
+  // Boolean
+  inStock: z.boolean().catch(true),
+})
+```
+
+## Search Params 업데이트
+
+### Link로 업데이트
+
+```tsx
+import { Link } from '@tanstack/react-router'
+
+// 전체 교체
+<Link to="/products" search={{ page: 1, sort: 'newest' }}>
+  Reset
+</Link>
+
+// 병합
+<Link to="/products" search={prev => ({ ...prev, page: 2 })}>
+  Next Page
+</Link>
+
+// 특정 값만 변경
+<Link
+  to="/products"
+  search={prev => ({ ...prev, sort: 'price' })}
+>
+  Sort by Price
+</Link>
+```
+
+### useNavigate로 업데이트
+
+```tsx
+import { useNavigate } from '@tanstack/react-router'
+
+function Pagination() {
+  const navigate = useNavigate()
+  const { page } = Route.useSearch()
+
+  const goToPage = (newPage: number) => {
+    navigate({
+      to: '/products',
+      search: prev => ({ ...prev, page: newPage }),
+    })
+  }
+
+  return (
+    <div>
+      <button onClick={() => goToPage(page - 1)} disabled={page <= 1}>
+        Prev
+      </button>
+      <span>Page {page}</span>
+      <button onClick={() => goToPage(page + 1)}>
+        Next
+      </button>
+    </div>
+  )
+}
+```
+
+## 실전 예시
+
+### 필터 + 정렬 + 페이지네이션
+
+```tsx
+import { createFileRoute, Link, useNavigate } from '@tanstack/react-router'
+import { z } from 'zod'
+
+const searchSchema = z.object({
+  page: z.number().min(1).catch(1),
+  pageSize: z.number().catch(10),
+  search: z.string().catch(''),
+  category: z.enum(['all', 'tech', 'lifestyle']).catch('all'),
+  sort: z.enum(['newest', 'oldest', 'popular']).catch('newest'),
+})
+
+export const Route = createFileRoute('/posts')({
+  validateSearch: searchSchema,
+  loaderDeps: ({ search }) => ({ search }),  // search 변경 시 loader 재실행
+  loader: async ({ deps: { search } }) => {
+    return fetchPosts(search)
+  },
+  component: PostsPage,
+})
+
+function PostsPage() {
+  const { page, search, category, sort } = Route.useSearch()
+  const posts = Route.useLoaderData()
+  const navigate = useNavigate()
+
+  const updateSearch = (updates: Partial<typeof searchSchema._type>) => {
+    navigate({
+      to: '/posts',
+      search: prev => ({ ...prev, ...updates, page: 1 }),  // 필터 변경 시 1페이지로
+    })
+  }
+
+  return (
+    <div>
+      {/* 검색 */}
+      <input
+        value={search}
+        onChange={e => updateSearch({ search: e.target.value })}
+        placeholder="Search..."
+      />
+
+      {/* 카테고리 필터 */}
+      <select
+        value={category}
+        onChange={e => updateSearch({ category: e.target.value as any })}
+      >
+        <option value="all">All</option>
+        <option value="tech">Tech</option>
+        <option value="lifestyle">Lifestyle</option>
+      </select>
+
+      {/* 정렬 */}
+      <select
+        value={sort}
+        onChange={e => updateSearch({ sort: e.target.value as any })}
+      >
+        <option value="newest">Newest</option>
+        <option value="oldest">Oldest</option>
+        <option value="popular">Popular</option>
+      </select>
+
+      {/* 목록 */}
+      {posts.map(post => (
+        <div key={post.id}>{post.title}</div>
+      ))}
+    </div>
+  )
+}
+```
+
+## loaderDeps
+
+Search params 변경 시 loader 재실행하려면 `loaderDeps` 필요.
+
+```tsx
+export const Route = createFileRoute('/products')({
+  validateSearch: searchSchema,
+  loaderDeps: ({ search }) => ({ search }),  // 의존성 선언
+  loader: async ({ deps: { search } }) => {
+    return fetchProducts(search)
+  },
+})
+```