@kood/claude-code 0.1.6 → 0.1.7

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

@@ -1,142 +1,64 @@
 # TanStack Start - Middleware
 
-> **상위 문서**: [TanStack Start](./index.md)
+Server Function 및 라우트에 공통 로직 적용.
 
-미들웨어는 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')
+    console.log('Processing request')
     return next()
   })
 
-// 미들웨어 적용
+// 적용
 const fn = createServerFn()
   .middleware([loggingMiddleware])
-  .handler(async () => {
-    return { message: 'Hello' }
-  })
+  .handler(async () => ({ 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()
+const authMiddleware = createMiddleware({ type: 'function' })
+  .server(async ({ next }) => {
+    const session = await getSession()
+    if (!session) throw redirect({ to: '/login' })
+    return next({ context: { user: session.user } })
   })
-```
 
-## 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],
-  }
-})
+// 사용
+export const protectedFn = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => ({ user: context.user }))
 ```
 
-## Global Server Function Middleware
+## Zod Validation Middleware
 
 ```typescript
-// src/start.ts
-import { createStart } from '@tanstack/react-start'
-import { loggingMiddleware } from './middleware'
-
-export const startInstance = createStart(() => {
-  return {
-    functionMiddleware: [loggingMiddleware],
-  }
-})
+const workspaceMiddleware = createMiddleware({ type: 'function' })
+  .inputValidator(zodValidator(z.object({ workspaceId: z.string() })))
+  .server(({ next, data }) => next())
 ```
 
-## Route-Level Middleware
+## Global 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}!`)
-      },
-    },
-  },
-})
+// src/start.ts
+export const startInstance = createStart(() => ({
+  requestMiddleware: [globalMiddleware],  // 모든 요청
+  functionMiddleware: [loggingMiddleware], // 모든 Server Function
+}))
 ```
 
-## Handler-Specific Middleware
+## Route-Level
 
 ```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)
-          },
-        },
-      }),
+    middleware: [authMiddleware], // 모든 핸들러
+    handlers: { GET: async ({ request }) => new Response('Hello') },
   },
 })
 ```
-
-## 인증 미들웨어 예시
-
-```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 }
-  })
-```

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

@@ -1,163 +1,66 @@
 # TanStack Start - Routing
 
-> **상위 문서**: [TanStack Start](./index.md)
+파일 기반 라우팅.
 
-TanStack Start는 파일 기반 라우팅을 지원합니다.
-
-## 기본 라우트
+## 기본 패턴
 
 ```tsx
 // routes/about.tsx
-import { createFileRoute } from '@tanstack/react-router'
-
 export const Route = createFileRoute('/about')({
   component: AboutPage,
 })
 
-function AboutPage() {
-  return <h1>About</h1>
-}
-```
-
-## Loader를 사용한 데이터 로딩
-
-```tsx
-// routes/index.tsx
-import { createFileRoute } from '@tanstack/react-router'
-
+// Loader
 export const Route = createFileRoute('/')({
   component: Page,
-  loader: async () => {
-    const res = await fetch('https://api.example.com/posts')
-    return res.json()
-  },
+  loader: async () => fetch('/api/posts').then(r => r.json()),
 })
 
 function Page() {
   const posts = Route.useLoaderData()
-  return (
-    <ul>
-      {posts.map((post) => (
-        <li key={post.id}>{post.title}</li>
-      ))}
-    </ul>
-  )
+  return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
 }
-```
-
-## 동적 라우트
-
-```tsx
-// routes/users/$id.tsx
-import { createFileRoute } from '@tanstack/react-router'
 
+// 동적 라우트
 export const Route = createFileRoute('/users/$id')({
-  loader: async ({ params }) => {
-    const user = await getUserById(params.id)
-    return { user }
-  },
-  component: UserDetailPage,
-})
-
-function UserDetailPage() {
-  const { user } = Route.useLoaderData()
-  return <h1>{user.name}</h1>
-}
-```
-
-## SSR 설정
-
-```tsx
-// routes/posts/$postId.tsx
-export const Route = createFileRoute('/posts/$postId')({
-  ssr: true,  // SSR 활성화
-  beforeLoad: () => {
-    console.log('서버에서 초기 요청 시 실행')
-  },
-  loader: () => {
-    console.log('서버에서 초기 요청 시 실행')
+  loader: async ({ params }) => ({ user: await getUserById(params.id) }),
+  component: () => {
+    const { user } = Route.useLoaderData()
+    return <h1>{user.name}</h1>
   },
-  component: () => <div>서버에서 렌더링됨</div>,
 })
 ```
 
-### SSR 옵션
+## SSR 옵션
 
 ```typescript
-// ssr: true - 전체 SSR (기본값)
-// ssr: false - 클라이언트 사이드만
-// ssr: 'data-only' - 데이터만 서버에서 로드, 렌더링은 클라이언트
+ssr: true       // 전체 SSR (기본값)
+ssr: false      // 클라이언트만
+ssr: 'data-only' // 데이터만 서버, 렌더링은 클라이언트
 ```
 
 ## Server Routes (API)
 
-### 기본 API 라우트
-
 ```typescript
-// routes/api/hello.ts
-import { createFileRoute } from '@tanstack/react-router'
-
 export const Route = createFileRoute('/api/hello')({
   server: {
     handlers: {
-      GET: async ({ request }) => {
-        return new Response('Hello, World!')
-      },
+      GET: async () => new Response('Hello'),
       POST: async ({ request }) => {
         const body = await request.json()
-        return new Response(`Hello, ${body.name}!`)
+        return json({ name: body.name })
       },
     },
   },
 })
 ```
 
-### JSON 응답
-
-```typescript
-import { createFileRoute } from '@tanstack/react-router'
-import { json } from '@tanstack/react-start'
-
-export const Route = createFileRoute('/api/users')({
-  server: {
-    handlers: {
-      GET: async ({ request }) => {
-        const users = await getUsers()
-        return json({ users })
-      },
-    },
-  },
-})
-```
-
-## 라우트 파일 구조
+## 구조
 
 ```
 routes/
-├── __root.tsx           → Root layout
-├── index.tsx            → /
-├── about.tsx            → /about
-├── users/
-│   ├── index.tsx        → /users
-│   └── $id.tsx          → /users/:id
-├── posts/
-│   ├── index.tsx        → /posts
-│   ├── $postId.tsx      → /posts/:postId
-│   └── new.tsx          → /posts/new
-└── api/
-    ├── hello.ts         → /api/hello
-    └── users.ts         → /api/users
-```
-
-## Catch-All 라우트
-
-```tsx
-// routes/$.tsx - 모든 매칭되지 않는 경로 처리
-export const Route = createFileRoute('/$')({
-  component: NotFoundPage,
-})
-
-function NotFoundPage() {
-  return <h1>404 - Page Not Found</h1>
-}
+├── __root.tsx      → Root layout
+├── index.tsx       → /
+├── users/$id.tsx   → /users/:id
+├── $.tsx           → Catch-all (404)
 ```

package/templates/tanstack-start/docs/library/tanstack-start/server-functions.md

@@ -1,287 +1,75 @@
 # TanStack Start - Server Functions
 
-> **상위 문서**: [TanStack Start](./index.md)
-
-Server Functions는 서버에서만 실행되는 타입 안전한 함수입니다.
+서버에서만 실행되는 타입 안전한 함수.
 
 ## ⚠️ 필수: TanStack Query 사용
 
-**Server Function을 클라이언트에서 호출할 때는 반드시 TanStack Query를 사용해야 합니다.**
-
-```
-❌ 금지: Server Function 직접 호출
-✅ 필수: useQuery/useMutation과 함께 사용
-```
-
-**이유**:
-- 자동 캐싱 및 중복 요청 제거
-- 로딩/에러 상태 관리
-- 자동 재시도 및 백그라운드 갱신
-- invalidateQueries로 일관된 데이터 동기화
+클라이언트 호출 시 반드시 useQuery/useMutation 사용.
+- 자동 캐싱, 중복 요청 제거, 로딩/에러 상태 관리, invalidateQueries 동기화
 
-## 기본 Server Function
+## 기본 패턴
 
 ```typescript
-import { createServerFn } from '@tanstack/react-start'
-
-// GET 요청 (데이터 조회)
+// GET
 export const getUsers = createServerFn({ method: 'GET' })
-  .handler(async () => {
-    return prisma.user.findMany()
-  })
-
-// POST 요청 (데이터 생성/수정)
-export const createUser = createServerFn({ method: 'POST' })
-  .handler(async () => {
-    return { success: true }
-  })
-```
-
-## Input Validation
-
-### 기본 Validator
-
-```typescript
-import { createServerFn } from '@tanstack/react-start'
-
-export const createUser = createServerFn({ method: 'POST' })
-  .inputValidator((data: { email: string; name: string }) => data)
-  .handler(async ({ data }) => {
-    // data는 타입 안전함
-    return prisma.user.create({ data })
-  })
-```
-
-### Zod Validation 사용
-
-```typescript
-import { createServerFn } from '@tanstack/react-start'
-import { zodValidator } from '@tanstack/react-start/validators'
-import { z } from 'zod'
+  .handler(async () => prisma.user.findMany())
 
+// POST + Zod Validation
 const createUserSchema = z.object({
-  email: z.string().email(),
+  email: z.email(),
   name: z.string().min(1).max(100),
-  bio: z.string().max(500).optional(),
 })
 
 export const createUser = createServerFn({ method: 'POST' })
   .inputValidator(zodValidator(createUserSchema))
-  .handler(async ({ data }) => {
-    return prisma.user.create({ data })
-  })
-```
-
-## FormData 처리
-
-```typescript
-import { createServerFn } from '@tanstack/react-start'
-
-export const submitForm = createServerFn({ method: 'POST' })
-  .inputValidator((formData: FormData) => {
-    const name = formData.get('name') as string
-    const email = formData.get('email') as string
-    return { name, email }
-  })
-  .handler(async ({ data }) => {
-    return prisma.user.create({ data })
-  })
+  .handler(async ({ data }) => prisma.user.create({ data }))
 ```
 
-## 컴포넌트에서 호출 (TanStack Query 필수)
-
-### ✅ 올바른 패턴: useQuery 사용 (데이터 조회)
+## 컴포넌트에서 호출
 
 ```tsx
-import { useQuery } from '@tanstack/react-query'
-import { getServerPosts } from '@/lib/server-functions'
-
-function PostList() {
-  const { data, isLoading, error } = useQuery({
-    queryKey: ['posts'],
-    queryFn: () => getServerPosts(),
-  })
-
-  if (isLoading) return <div>Loading...</div>
-  if (error) return <div>Error: {error.message}</div>
-
-  return (
-    <ul>
-      {data?.map((post) => (
-        <li key={post.id}>{post.title}</li>
-      ))}
-    </ul>
-  )
-}
-```
-
-### ✅ 올바른 패턴: useMutation 사용 (데이터 변경)
-
-```tsx
-import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { createPost, deletePost } from '@/lib/server-functions'
-
-function PostForm() {
-  const queryClient = useQueryClient()
-
-  const mutation = useMutation({
-    mutationFn: (data: { title: string; content: string }) => createPost({ data }),
-    onSuccess: () => {
-      // 관련 쿼리 무효화로 데이터 동기화
-      queryClient.invalidateQueries({ queryKey: ['posts'] })
-    },
-  })
-
-  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
-    e.preventDefault()
-    const formData = new FormData(e.currentTarget)
-    mutation.mutate({
-      title: formData.get('title') as string,
-      content: formData.get('content') as string,
-    })
-  }
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <input name="title" required />
-      <textarea name="content" required />
-      <button type="submit" disabled={mutation.isPending}>
-        {mutation.isPending ? '저장 중...' : '저장'}
-      </button>
-    </form>
-  )
-}
-```
-
-### ❌ 금지: Server Function 직접 호출
-
-```tsx
-// ❌ 이렇게 하지 마세요!
-function BadExample() {
-  const [posts, setPosts] = useState([])
-  const [loading, setLoading] = useState(false)
-
-  useEffect(() => {
-    setLoading(true)
-    getPosts()
-      .then(setPosts)
-      .finally(() => setLoading(false))
-  }, [])
-
-  // 문제점:
-  // - 중복 요청 발생 가능
-  // - 캐싱 없음
-  // - 에러 처리 수동
-  // - 다른 컴포넌트와 데이터 동기화 안됨
-}
-```
-
-## ⚠️ 함수 분리 시 유의사항
-
-Server Function 내부 로직을 별도 함수로 분리할 때 반드시 아래 규칙을 따르세요.
+// ✅ useQuery (조회)
+const { data, isLoading } = useQuery({
+  queryKey: ['posts'],
+  queryFn: () => getServerPosts(),
+})
 
-### 규칙
+// ✅ useMutation (변경)
+const mutation = useMutation({
+  mutationFn: createPost,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
+})
 
-```
-1. 분리한 함수는 createServerFn 내부에서만 호출
-2. 분리한 함수는 createServerFn으로 감싸지 않음
-3. 분리한 함수는 index.ts에서 export 금지 (프론트엔드 import 방지)
+// ❌ 직접 호출 금지 (캐싱 없음, 동기화 안됨)
 ```
 
-### ✅ 올바른 패턴
+## 함수 분리 규칙
 
 ```typescript
-// services/user/mutations.ts
-
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// 내부 헬퍼 함수 (export 금지!)
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-const validateUserData = async (email: string) => {
-  const existing = await prisma.user.findUnique({ where: { email } })
-  if (existing) throw new Error('Email already exists')
-  return true
-}
+// 내부 헬퍼 (export 금지!)
+const validateUserData = async (email: string) => { ... }
 
-const sendWelcomeEmail = async (userId: string, email: string) => {
-  await emailService.send({
-    to: email,
-    template: 'welcome',
-    data: { userId },
-  })
-}
-
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Server Function (export 가능)
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 export const createUser = createServerFn({ method: 'POST' })
   .inputValidator(createUserSchema)
   .handler(async ({ data }) => {
-    // 내부 헬퍼 함수 호출
     await validateUserData(data.email)
-
-    const user = await prisma.user.create({ data })
-
-    // 내부 헬퍼 함수 호출
-    await sendWelcomeEmail(user.id, user.email)
-
-    return user
-  })
-```
-
-```typescript
-// services/user/index.ts
-
-// ✅ Server Function만 export
-export { createUser, updateUser, deleteUser } from './mutations'
-export { getUsers, getUserById } from './queries'
-
-// ❌ 내부 헬퍼 함수는 export 금지!
-// export { validateUserData, sendWelcomeEmail } from './mutations'
-```
-
-### ❌ 잘못된 패턴
-
-```typescript
-// ❌ 분리한 함수를 createServerFn으로 감싸지 마세요
-export const validateUserData = createServerFn({ method: 'POST' })
-  .handler(async ({ data }) => {
-    // ...
+    return prisma.user.create({ data })
   })
 
-// ❌ 내부 헬퍼 함수를 export 하지 마세요
-export const sendWelcomeEmail = async (userId: string) => {
-  // 프론트엔드에서 import 가능해져 보안 위험!
-}
+// index.ts: Server Function만 export
+export { createUser } from './mutations'
+// ❌ export { validateUserData } 금지
 ```
 
-### 이유
-
-- **보안**: 내부 로직이 프론트엔드 번들에 포함되지 않음
-- **명확한 API**: Server Function만 외부에 노출되어 API 경계가 명확함
-- **트리 쉐이킹**: export하지 않은 함수는 번들에서 제거됨
-
----
-
-## 보안 패턴
-
-### 서버 전용 데이터 보호
+## 보안
 
 ```tsx
-// ❌ 잘못된 방법 - 클라이언트에 노출됨
-export const Route = createFileRoute('/users')({
-  loader: () => {
-    const secret = process.env.SECRET // 클라이언트에 노출!
-    return fetch(`/api/users?key=${secret}`)
-  },
-})
-
-// ✅ 올바른 방법 - 서버 함수 사용
-const getUsersSecurely = createServerFn().handler(() => {
-  const secret = process.env.SECRET // 서버에서만 접근
-  return fetch(`/api/users?key=${secret}`)
-})
+// ❌ loader에서 환경변수 직접 사용 (노출됨)
+loader: () => { const secret = process.env.SECRET }
 
-export const Route = createFileRoute('/users')({
-  loader: () => getUsersSecurely(),
+// ✅ Server Function 사용
+const fn = createServerFn().handler(() => {
+  const secret = process.env.SECRET // 서버에서만
 })
 ```