@kood/claude-code 0.1.0

package/templates/tanstack-start/docs/library/tanstack-query/use-query.md

@@ -0,0 +1,173 @@
+# TanStack Query - useQuery
+
+> **상위 문서**: [TanStack Query](./index.md)
+
+## 기본 사용법
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function Todos() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: getTodos,
+  })
+
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+
+  return (
+    <ul>
+      {data?.map((todo) => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## useQuery 반환 값
+
+```typescript
+const {
+  data,           // 쿼리 결과 데이터
+  error,          // 에러 객체
+  isLoading,      // 첫 로딩 중
+  isFetching,     // 백그라운드 페칭 중
+  isError,        // 에러 상태
+  isSuccess,      // 성공 상태
+  isPending,      // 데이터 없고 로딩 중
+  isStale,        // 데이터가 stale 상태
+  refetch,        // 수동 리페치 함수
+  status,         // 'pending' | 'error' | 'success'
+  fetchStatus,    // 'fetching' | 'paused' | 'idle'
+} = useQuery({ queryKey, queryFn })
+```
+
+## useQuery 옵션
+
+```tsx
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+
+  // 캐시 관련
+  staleTime: 1000 * 60 * 5,     // 5분 동안 fresh
+  gcTime: 1000 * 60 * 30,       // 30분 후 가비지 컬렉션
+
+  // 리페치 관련
+  refetchOnWindowFocus: true,   // 윈도우 포커스 시 리페치
+  refetchOnReconnect: true,     // 네트워크 재연결 시 리페치
+  refetchInterval: 1000 * 60,   // 1분마다 리페치
+
+  // 재시도 관련
+  retry: 3,                     // 실패 시 재시도 횟수
+  retryDelay: 1000,             // 재시도 딜레이
+
+  // 조건부 실행
+  enabled: !!userId,            // false면 쿼리 실행 안 함
+
+  // 초기 데이터
+  initialData: [],              // 초기 데이터
+
+  // 플레이스홀더
+  placeholderData: [],          // 로딩 중 임시 데이터
+})
+```
+
+## 파라미터가 있는 쿼리
+
+```tsx
+function Todo({ todoId }: { todoId: number }) {
+  const { data } = useQuery({
+    queryKey: ['todo', todoId],
+    queryFn: () => fetchTodoById(todoId),
+    enabled: !!todoId,
+  })
+
+  return <div>{data?.title}</div>
+}
+```
+
+## 의존적 쿼리
+
+```tsx
+function UserPosts({ userId }: { userId: number }) {
+  // 먼저 유저 정보를 가져옴
+  const { data: user } = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetchUserById(userId),
+  })
+
+  // 유저 정보가 있어야 포스트를 가져옴
+  const { data: posts } = useQuery({
+    queryKey: ['posts', user?.id],
+    queryFn: () => fetchPostsByUserId(user!.id),
+    enabled: !!user?.id,
+  })
+
+  return (
+    <div>
+      <h1>{user?.name}</h1>
+      <ul>
+        {posts?.map((post) => (
+          <li key={post.id}>{post.title}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+## 병렬 쿼리
+
+```tsx
+function Dashboard() {
+  const usersQuery = useQuery({ queryKey: ['users'], queryFn: fetchUsers })
+  const postsQuery = useQuery({ queryKey: ['posts'], queryFn: fetchPosts })
+
+  if (usersQuery.isLoading || postsQuery.isLoading) {
+    return <div>Loading...</div>
+  }
+
+  return (
+    <div>
+      <UserList users={usersQuery.data} />
+      <PostList posts={postsQuery.data} />
+    </div>
+  )
+}
+```
+
+## useQueries (동적 병렬 쿼리)
+
+```tsx
+function UsersList({ userIds }: { userIds: number[] }) {
+  const userQueries = useQueries({
+    queries: userIds.map((id) => ({
+      queryKey: ['user', id],
+      queryFn: () => fetchUserById(id),
+    })),
+  })
+
+  return (
+    <ul>
+      {userQueries.map((query, index) => (
+        <li key={userIds[index]}>
+          {query.isLoading ? 'Loading...' : query.data?.name}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Select로 데이터 변환
+
+```tsx
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  select: (todos) => todos.filter((todo) => todo.completed),
+})
+```

package/templates/tanstack-start/docs/library/tanstack-start/auth-patterns.md

@@ -0,0 +1,171 @@
+# TanStack Start - 인증 패턴
+
+> **상위 문서**: [TanStack Start](./index.md)
+
+TanStack Start에서의 인증 구현 패턴입니다.
+
+## 로그인
+
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+import { redirect } from '@tanstack/react-router'
+import bcrypt from 'bcryptjs'
+
+export const loginFn = createServerFn({ method: 'POST' })
+  .inputValidator((data: { email: string; password: string }) => data)
+  .handler(async ({ data }) => {
+    const user = await authenticateUser(data.email, data.password)
+
+    if (!user) {
+      return { error: 'Invalid credentials' }
+    }
+
+    const session = await useAppSession()
+    await session.update({
+      userId: user.id,
+      email: user.email,
+    })
+
+    throw redirect({ to: '/dashboard' })
+  })
+```
+
+## 로그아웃
+
+```typescript
+export const logoutFn = createServerFn({ method: 'POST' })
+  .handler(async () => {
+    const session = await useAppSession()
+    await session.clear()
+    throw redirect({ to: '/' })
+  })
+```
+
+## 현재 사용자 조회
+
+```typescript
+export const getCurrentUserFn = createServerFn({ method: 'GET' })
+  .handler(async () => {
+    const session = await useAppSession()
+    const userId = session.data.userId
+
+    if (!userId) {
+      return null
+    }
+
+    return await getUserById(userId)
+  })
+```
+
+## 회원가입
+
+```typescript
+export const registerFn = createServerFn({ method: 'POST' })
+  .inputValidator((data: { email: string; password: string; name: string }) => data)
+  .handler(async ({ data }) => {
+    const existingUser = await getUserByEmail(data.email)
+    if (existingUser) {
+      return { error: 'User already exists' }
+    }
+
+    const hashedPassword = await bcrypt.hash(data.password, 12)
+
+    const user = await createUser({
+      email: data.email,
+      password: hashedPassword,
+      name: data.name,
+    })
+
+    const session = await useAppSession()
+    await session.update({ userId: user.id })
+
+    return { success: true, user: { id: user.id, email: user.email } }
+  })
+```
+
+## 인증 미들웨어
+
+```typescript
+import { createMiddleware } from '@tanstack/react-start'
+import { redirect } from '@tanstack/react-router'
+
+export const authMiddleware = createMiddleware({ type: 'function' })
+  .server(async ({ next }) => {
+    const session = await useAppSession()
+
+    if (!session.data.userId) {
+      throw redirect({ to: '/login' })
+    }
+
+    const user = await getUserById(session.data.userId)
+
+    return next({ context: { user } })
+  })
+```
+
+## 보호된 Server Function
+
+```typescript
+export const getProtectedData = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    // context.user 사용 가능
+    return {
+      message: `Hello, ${context.user.name}!`,
+      data: await getPrivateData(context.user.id),
+    }
+  })
+```
+
+## 보호된 라우트
+
+```tsx
+// routes/dashboard.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/dashboard')({
+  beforeLoad: async () => {
+    const user = await getCurrentUserFn()
+
+    if (!user) {
+      throw redirect({ to: '/login' })
+    }
+
+    return { user }
+  },
+  component: DashboardPage,
+})
+
+function DashboardPage() {
+  const { user } = Route.useRouteContext()
+  return <h1>Welcome, {user.name}!</h1>
+}
+```
+
+## Better Auth 통합
+
+```typescript
+// lib/auth.ts
+import { betterAuth } from 'better-auth'
+import { prismaAdapter } from 'better-auth/adapters/prisma'
+import { prisma } from './prisma'
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma),
+  emailAndPassword: {
+    enabled: true,
+  },
+})
+
+// Server Function에서 사용
+import { createServerFn } from '@tanstack/react-start'
+import { auth } from '~/lib/auth'
+
+export const getSession = createServerFn({ method: 'GET' })
+  .handler(async ({ request }) => {
+    const session = await auth.api.getSession({
+      headers: request.headers,
+    })
+    return session
+  })
+```

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

@@ -0,0 +1,114 @@
+# TanStack Start
+
+> **Version**: 1.x | Full-stack React Framework
+
+---
+
+## ⛔ 필수 규칙
+
+```
+❌ /api 라우터 사용 금지 → Server Functions 사용
+❌ handler 내부 수동 검증 금지 → inputValidator 사용
+❌ handler 내부 수동 인증 체크 금지 → middleware 사용
+✅ POST/PUT/PATCH에는 반드시 inputValidator 추가
+✅ 인증 필요 시 반드시 middleware 추가
+```
+
+---
+
+## 🚀 Quick Reference (복사용)
+
+```typescript
+// ✅ Server Function (GET + 인증)
+export const getUsers = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])  // ⭐ 인증 미들웨어
+  .handler(async () => prisma.user.findMany())
+
+// ✅ Server Function (POST + Validation + 인증)
+export const createUser = createServerFn({ method: 'POST' })
+  .middleware([authMiddleware])        // ⭐ 인증 미들웨어
+  .inputValidator(createUserSchema)    // ⭐ Zod 스키마
+  .handler(async ({ data }) => prisma.user.create({ data }))
+
+// Route with Loader
+export const Route = createFileRoute('/users')({
+  component: UsersPage,
+  loader: async () => ({ users: await getUsers() }),
+})
+
+// Component에서 Loader 데이터 사용
+const UsersPage = (): JSX.Element => {
+  const { users } = Route.useLoaderData()
+  return <div>{/* render */}</div>
+}
+```
+
+### 라우트 파일 구조
+
+```
+routes/
+├── __root.tsx            # Root layout
+├── index.tsx             # /
+├── about.tsx             # /about
+└── users/
+    ├── index.tsx         # /users
+    ├── $id.tsx           # /users/:id
+    ├── -components/      # 페이지 전용 컴포넌트
+    └── -functions/       # 페이지 전용 Server Functions ⭐
+```
+
+### Server Functions 위치
+
+```
+공통 함수 (여러 라우트)  → @/functions/
+라우트 전용 함수         → routes/[경로]/-functions/
+```
+
+---
+
+## 문서 구조
+
+- [설치 및 설정](./setup.md) - 패키지 설치, Vite 설정, TypeScript 설정
+- [Server Functions](./server-functions.md) - 서버 함수 정의 및 사용법
+- [Middleware](./middleware.md) - 미들웨어 정의 및 적용
+- [Routing](./routing.md) - 파일 기반 라우팅, 동적 라우트, SSR
+- [인증 패턴](./auth-patterns.md) - 로그인, 로그아웃, 세션 관리
+
+## 빠른 시작
+
+```bash
+yarn add @tanstack/react-start @tanstack/react-router vinxi
+yarn add -D vite @vitejs/plugin-react vite-tsconfig-paths
+```
+
+## 핵심 개념
+
+### Server Functions
+서버에서만 실행되는 타입 안전한 함수를 정의합니다.
+
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+
+export const getData = createServerFn({ method: 'GET' })
+  .handler(async () => {
+    return { message: 'Hello from server' }
+  })
+```
+
+### File-based Routing
+파일 시스템 기반의 자동 라우팅을 지원합니다.
+
+```
+routes/
+├── index.tsx        → /
+├── about.tsx        → /about
+└── users/
+    ├── index.tsx    → /users
+    └── $id.tsx      → /users/:id
+```
+
+## 참고 자료
+
+- [TanStack Start 공식 문서](https://tanstack.com/start/latest)
+- [TanStack Router 문서](https://tanstack.com/router/latest)
+- [Vinxi 문서](https://vinxi.dev)

package/templates/tanstack-start/docs/library/tanstack-start/middleware.md

@@ -0,0 +1,142 @@
+# TanStack Start - Middleware
+
+> **상위 문서**: [TanStack Start](./index.md)
+
+미들웨어는 Server Function 및 라우트 핸들러에 공통 로직을 적용합니다.
+
+## Server Function Middleware
+
+```typescript
+import { createMiddleware, createServerFn } from '@tanstack/react-start'
+
+// 미들웨어 정의
+const loggingMiddleware = createMiddleware({ type: 'function' })
+  .client(() => {
+    console.log('Client: Server function called')
+  })
+  .server(({ next }) => {
+    console.log('Server: Processing request')
+    return next()
+  })
+
+// 미들웨어 적용
+const fn = createServerFn()
+  .middleware([loggingMiddleware])
+  .handler(async () => {
+    return { message: 'Hello' }
+  })
+```
+
+## Zod Validation Middleware
+
+```typescript
+import { createMiddleware } from '@tanstack/react-start'
+import { zodValidator } from '@tanstack/react-start/validators'
+import { z } from 'zod'
+
+const mySchema = z.object({
+  workspaceId: z.string(),
+})
+
+const workspaceMiddleware = createMiddleware({ type: 'function' })
+  .inputValidator(zodValidator(mySchema))
+  .server(({ next, data }) => {
+    console.log('Workspace ID:', data.workspaceId)
+    return next()
+  })
+```
+
+## Global Request Middleware
+
+```typescript
+// src/start.ts
+import { createStart, createMiddleware } from '@tanstack/react-start'
+
+const myGlobalMiddleware = createMiddleware().server(({ next }) => {
+  console.log('Global middleware running')
+  return next()
+})
+
+export const startInstance = createStart(() => {
+  return {
+    requestMiddleware: [myGlobalMiddleware],
+  }
+})
+```
+
+## Global Server Function Middleware
+
+```typescript
+// src/start.ts
+import { createStart } from '@tanstack/react-start'
+import { loggingMiddleware } from './middleware'
+
+export const startInstance = createStart(() => {
+  return {
+    functionMiddleware: [loggingMiddleware],
+  }
+})
+```
+
+## Route-Level Middleware
+
+```typescript
+export const Route = createFileRoute('/hello')({
+  server: {
+    middleware: [authMiddleware, loggerMiddleware], // 모든 핸들러에 적용
+    handlers: {
+      GET: async ({ request }) => {
+        return new Response('Hello, World! from ' + request.url)
+      },
+      POST: async ({ request }) => {
+        const body = await request.json()
+        return new Response(`Hello, ${body.name}!`)
+      },
+    },
+  },
+})
+```
+
+## Handler-Specific Middleware
+
+```typescript
+export const Route = createFileRoute('/hello')({
+  server: {
+    handlers: ({ createHandlers }) =>
+      createHandlers({
+        GET: {
+          middleware: [loggerMiddleware], // GET에만 적용
+          handler: async ({ request }) => {
+            return new Response('Hello, World! from ' + request.url)
+          },
+        },
+      }),
+  },
+})
+```
+
+## 인증 미들웨어 예시
+
+```typescript
+import { createMiddleware } from '@tanstack/react-start'
+import { redirect } from '@tanstack/react-router'
+
+const authMiddleware = createMiddleware({ type: 'function' })
+  .server(async ({ next }) => {
+    const session = await getSession()
+
+    if (!session) {
+      throw redirect({ to: '/login' })
+    }
+
+    return next({ context: { user: session.user } })
+  })
+
+// 사용
+export const protectedFn = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    // context.user 사용 가능
+    return { user: context.user }
+  })
+```