@kood/claude-code 0.6.6 → 0.7.0

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

@@ -1,29 +1,34 @@
-# TanStack Start
-
-> v1 | Full-stack React Framework
-
----
+# TanStack Start Documentation
 
 <context>
 
-**Purpose:** TanStack Start를 사용한 Full-stack React 애플리케이션 개발 가이드
-
-**Scope:**
-- Server Functions (타입 안전 API)
-- File-based Routing (TanStack Router)
-- Middleware 체계
-- SSR + Streaming
-- TanStack Query 통합
+**목적**: TanStack Start 애플리케이션 개발을 위한 AI Agent 최적화 문서
 
-**Key Features:**
-- Type-safe Server Functions
-- Zero-config file-based routing
-- Built-in middleware system
-- First-class SSR support
-- Seamless TanStack Query integration
-- Multiple deployment targets (Vercel, Cloudflare, Nitro)
+**버전**: v1.x (RC, ~v1.159.x)
 
-**Version:** v1.x
+**핵심 특징**:
+- Type-safe, full-stack React framework
+- File-based routing with Vite-powered build
+- Server Functions로 type-safe API 구축
+- Built-in SWR caching (staleTime, gcTime, shouldReload)
+- Streaming SSR 지원
+- TanStack Query 통합
+- Multiple deployment targets (Cloudflare, Netlify, Vercel, Railway, Node, Bun)
+- React Server Components 지원 예정 (non-breaking v1.x addition)
+
+**주요 패키지 변경사항**:
+- `@tanstack/start` → `@tanstack/react-start` (v1.121.0+)
+- Build system: Vinxi → Vite
+- `.validator()` → `.inputValidator()` (deprecated)
+- `createAPIFileRoute()` → `createServerFileRoute()` with `.methods()`
+
+**런타임 요구사항**:
+| 패키지 | 버전 |
+|--------|------|
+| Node.js | >=22.12.0 |
+| React | 18+ or 19+ |
+| Vite | 7+ |
+| TypeScript | 5.x |
 
 </context>
 
@@ -31,17 +36,20 @@
 
 <forbidden>
 
-| 분류 | ❌ 금지 | 이유 |
-|------|---------|------|
-| **API 라우터** | `/api` 경로에 라우터 생성 | Server Functions 사용 |
-| **수동 검증** | handler 내부에서 Zod 수동 검증 | `.inputValidator()` 사용 |
-| **수동 인증** | handler 내부에서 세션 체크 | `.middleware()` 사용 |
-| **deprecated API** | `.validator()` 메서드 | `.inputValidator()` 사용 (v1) |
-| **직접 호출** | 컴포넌트에서 Server Function 직접 호출 | TanStack Query 사용 필수 |
-| **환경변수 노출** | loader에서 `process.env` 직접 사용 | Server Function에서만 |
-| **헬퍼 export** | 내부 헬퍼 함수 export | Server Function만 export |
-| **any 타입** | Server Function 파라미터에 any | 명시적 타입/Zod 스키마 |
-| **일반 함수** | 일반 async 함수를 API로 사용 | `createServerFn()` 사용 |
+| 패턴 | 이유 |
+|------|------|
+| `@tanstack/start` 패키지 사용 | v1.121.0+부터 `@tanstack/react-start`로 변경됨 |
+| `.validator()` 사용 | Deprecated. `.inputValidator()` 사용 필수 |
+| `createAPIFileRoute()` 사용 | Deprecated. `createServerFileRoute().methods()` 사용 |
+| Vinxi config 참조 | Vite로 마이그레이션됨 |
+| Server Function 내 `import.meta.env` | 클라이언트 전용. `process.env` 사용 |
+| Client에서 `process.env` | 서버 전용. `import.meta.env.VITE_*` 사용 |
+| `tsconfig.json`에 `verbatimModuleSyntax: true` | TanStack Start와 호환성 문제 발생 |
+| Server Function에 민감 정보 직접 노출 | 클라이언트 번들에 포함됨. Helper function 분리 필수 |
+| `any` 타입 사용 | Type safety 상실. `unknown` 또는 명시적 타입 사용 |
+| Middleware 없이 인증 로직 | 보안 취약. `createMiddleware` 사용 필수 |
+| Route 파일에 비즈니스 로직 | 관심사 분리. `-functions/` 디렉토리 사용 |
+| `gcTime: 0` 남발 | 캐시 무효화. 필요한 경우만 사용 |
 
 </forbidden>
 
@@ -49,16 +57,20 @@
 
 <required>
 
-| 분류 | ✅ 필수 | 상세 |
-|------|---------|------|
-| **POST/PUT/PATCH** | `.inputValidator()` 사용 | Zod 스키마로 검증 |
-| **인증 필요** | `.middleware()` 사용 | authMiddleware 적용 |
-| **클라이언트 호출** | TanStack Query 사용 | useQuery/useMutation |
-| **Server Function** | `createServerFn()` 사용 | method 명시 (GET/POST/etc) |
-| **타입 안전성** | 명시적 return type | TypeScript strict 모드 |
-| **파일 구조** | `-functions/` 폴더 사용 | 페이지 전용 함수 분리 |
-| **공통 함수** | `@/functions/` 사용 | 재사용 가능한 함수 |
-| **환경변수** | Server Function 내부에서만 | 클라이언트 노출 방지 |
+| 패턴 | 세부사항 |
+|------|----------|
+| `@tanstack/react-start` 패키지 | v1.121.0+ 필수 패키지명 |
+| `.inputValidator()` | POST/PUT/PATCH/DELETE Server Function에 필수 |
+| Zod schema 검증 | 모든 입력값 검증 (`z.email()`, `z.url()` 등) |
+| Middleware로 인증 처리 | `createMiddleware`로 auth 로직 중앙화 |
+| Helper functions 분리 | Server Function 외부에 민감 로직 격리 |
+| 명시적 return type | 모든 함수에 타입 명시 |
+| `strictNullChecks: true` | TypeScript config에 권장 |
+| Server Routes는 `createServerFileRoute()` | API 엔드포인트용 새 API |
+| Environment variables 분리 | Server: `process.env`, Client: `import.meta.env.VITE_*` |
+| TanStack Query로 Server Function 호출 | `useSuspenseQuery`, `useMutation` 사용 |
+| `-components/`, `-hooks/`, `-functions/` 컨벤션 | 파일 구조화 규칙 |
+| `beforeLoad`로 인증 가드 | Route-level 접근 제어 |
 
 </required>
 
@@ -69,52 +81,118 @@
 ## 설치
 
 ```bash
-yarn add @tanstack/react-start @tanstack/react-router vinxi
-yarn add -D vite @vitejs/plugin-react vite-tsconfig-paths
+# New project
+npm create @tanstack/start@latest
+
+# Dependencies
+npm install @tanstack/react-start@latest @tanstack/react-router@latest
+npm install -D @tanstack/router-plugin vite typescript
 ```
 
-## 설정
+## vite.config.ts
 
 ```typescript
-// vite.config.ts
 import { defineConfig } from 'vite'
-import tsConfigPaths from 'vite-tsconfig-paths'
-import { tanstackStart } from '@tanstack/react-start/plugin/vite'
-import viteReact from '@vitejs/plugin-react'
+import react from '@vitejs/plugin-react'
+import { tanstackRouterPlugin } from '@tanstack/router-plugin/vite'
 
 export default defineConfig({
-  server: { port: 3000 },
-  plugins: [tsConfigPaths(), tanstackStart(), viteReact()],
+  plugins: [
+    tanstackRouterPlugin(),
+    react(),
+  ],
+  server: {
+    port: 3000,
+  },
 })
 ```
 
+## tsconfig.json
+
 ```json
-// tsconfig.json
 {
   "compilerOptions": {
     "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
+    "moduleResolution": "Bundler",
     "jsx": "react-jsx",
-    "paths": { "@/*": ["./src/*"] }
+    "strict": false,
+    "strictNullChecks": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["app/**/*"],
+  "exclude": ["node_modules"]
+}
+```
+
+**주의**: `verbatimModuleSyntax: true` 사용 금지 (호환성 문제)
+
+## Environment Variables
+
+### Server-only (.env)
+
+```bash
+# Server-only (process.env)
+DATABASE_URL="postgresql://..."
+AUTH_SECRET="secret-key"
+STRIPE_SECRET_KEY="sk_test_..."
+```
+
+### Client-exposed (.env)
+
+```bash
+# Client-exposed (import.meta.env.VITE_*)
+VITE_API_URL="https://api.example.com"
+VITE_PUBLIC_KEY="pk_test_..."
+```
+
+### 사용 예시
+
+```typescript
+// ✅ Server Function
+export const getSecretData = createServerFn({ method: 'GET' }).handler(
+  async () => {
+    const secret = process.env.AUTH_SECRET // OK
+    return { data: 'protected' }
   }
+)
+
+// ✅ Client Component
+function App() {
+  const apiUrl = import.meta.env.VITE_API_URL // OK
+  return <div>{apiUrl}</div>
 }
+
+// ❌ Wrong
+export const wrongFn = createServerFn({ method: 'GET' }).handler(async () => {
+  const key = import.meta.env.VITE_SECRET // ❌ 서버에서 import.meta.env 사용 금지
+  return key
+})
 ```
 
-## 환경 변수 검증
+### Validation (app/env.ts)
 
 ```typescript
-// lib/env.ts
 import { z } from 'zod'
 
-const envSchema = z.object({
-  NODE_ENV: z.enum(['development', 'production', 'test']),
+const serverEnvSchema = z.object({
   DATABASE_URL: z.string().url(),
-  API_SECRET: z.string().min(32),
+  AUTH_SECRET: z.string().min(32),
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+})
+
+const clientEnvSchema = z.object({
+  VITE_API_URL: z.string().url(),
 })
 
-export const env = envSchema.parse(process.env)
+export const serverEnv = serverEnvSchema.parse(process.env)
+
+export const clientEnv = clientEnvSchema.parse(import.meta.env)
 ```
 
 </setup>
@@ -123,184 +201,164 @@ export const env = envSchema.parse(process.env)
 
 <server_functions>
 
-## Server Functions
+## Server Functions 개요
 
-서버에서만 실행되는 타입 안전한 함수.
+Server Functions는 type-safe한 API 엔드포인트를 생성하는 TanStack Start의 핵심 기능입니다.
 
-### 기본 패턴
+**주요 특징**:
+- Type-safe client-server communication
+- Automatic serialization/deserialization
+- Middleware support
+- Input validation with Zod
+- Method-based routing (GET, POST, PUT, PATCH, DELETE)
 
-| 메서드 | 사용 시점 | inputValidator | middleware |
-|--------|----------|---------------|-----------|
-| **GET** | 데이터 조회 | ❌ 선택 | ✅ 인증 시 필수 |
-| **POST** | 데이터 생성 | ✅ 필수 | ✅ 인증 시 필수 |
-| **PUT** | 전체 수정 | ✅ 필수 | ✅ 인증 시 필수 |
-| **PATCH** | 부분 수정 | ✅ 필수 | ✅ 인증 시 필수 |
-| **DELETE** | 삭제 | ❌ 선택 | ✅ 인증 시 필수 |
+## createServerFn 패턴
 
-### GET: 데이터 조회
+### GET (Query)
 
 ```typescript
-// ✅ 기본 GET
-export const getUsers = createServerFn({ method: 'GET' })
-  .handler(async () => {
-    return prisma.user.findMany()
-  })
+// app/functions/users.ts
+import { createServerFn } from '@tanstack/react-start'
+import { z } from 'zod'
 
-// ✅ GET + 인증
-export const getMyProfile = createServerFn({ method: 'GET' })
-  .middleware([authMiddleware])
-  .handler(async ({ context }) => {
-    return prisma.user.findUnique({
-      where: { id: context.user.id },
-    })
-  })
+const getUserSchema = z.object({
+  id: z.string().uuid(),
+})
 
-// ✅ GET + Query Params (선택적 검증)
-export const getUserById = createServerFn({ method: 'GET' })
-  .inputValidator(z.object({ id: z.string() }))
+export const getUser = createServerFn({ method: 'GET' })
+  .inputValidator(getUserSchema)
   .handler(async ({ data }) => {
-    return prisma.user.findUnique({
-      where: { id: data.id },
-    })
+    const user = await db.user.findUnique({ where: { id: data.id } })
+    if (!user) throw new Error('User not found')
+    return user
   })
 ```
 
-### POST: 데이터 생성
+### POST (Create)
 
 ```typescript
-// ✅ POST + inputValidator 필수
+// app/functions/users.ts
+import { createServerFn } from '@tanstack/react-start'
+import { z } from 'zod'
+
 const createUserSchema = z.object({
   email: z.email(),
-  name: z.string().min(1).max(100).trim(),
-  age: z.number().int().min(0).optional(),
+  name: z.string().min(2),
+  website: z.url().optional(),
 })
 
 export const createUser = createServerFn({ method: 'POST' })
   .inputValidator(createUserSchema)
-  .handler(async ({ data }) => {
-    // data는 자동으로 검증됨
-    return prisma.user.create({ data })
-  })
-
-// ✅ POST + inputValidator + 인증
-export const createPost = createServerFn({ method: 'POST' })
   .middleware([authMiddleware])
-  .inputValidator(z.object({
-    title: z.string().min(1).max(200),
-    content: z.string().min(1),
-  }))
   .handler(async ({ data, context }) => {
-    return prisma.post.create({
+    const user = await db.user.create({
       data: {
         ...data,
-        authorId: context.user.id,
+        createdBy: context.user.id,
       },
     })
-  })
-
-// ❌ inputValidator 없이 POST (금지)
-export const badCreate = createServerFn({ method: 'POST' })
-  .handler(async ({ data }) => {
-    // data 타입 불안전, 검증 없음
-    return prisma.user.create({ data })
+    return user
   })
 ```
 
-### PUT/PATCH: 데이터 수정
+### PUT/PATCH (Update)
 
 ```typescript
-// ✅ PUT (전체 수정) + inputValidator 필수
+// app/functions/users.ts
 const updateUserSchema = z.object({
-  id: z.string(),
-  email: z.email(),
-  name: z.string().min(1).max(100),
+  id: z.string().uuid(),
+  email: z.email().optional(),
+  name: z.string().min(2).optional(),
 })
 
 export const updateUser = createServerFn({ method: 'PUT' })
-  .middleware([authMiddleware])
   .inputValidator(updateUserSchema)
-  .handler(async ({ data }) => {
-    return prisma.user.update({
-      where: { id: data.id },
-      data: { email: data.email, name: data.name },
-    })
-  })
+  .middleware([authMiddleware])
+  .handler(async ({ data, context }) => {
+    const { id, ...updates } = data
 
-// ✅ PATCH (부분 수정) + inputValidator 필수
-const patchUserSchema = z.object({
-  id: z.string(),
-  name: z.string().min(1).max(100).optional(),
-  age: z.number().int().min(0).optional(),
-})
+    // Authorization check
+    if (context.user.id !== id && context.user.role !== 'admin') {
+      throw new Error('Unauthorized')
+    }
 
-export const patchUser = createServerFn({ method: 'PATCH' })
-  .middleware([authMiddleware])
-  .inputValidator(patchUserSchema)
-  .handler(async ({ data }) => {
-    const { id, ...updateData } = data
-    return prisma.user.update({
+    const user = await db.user.update({
       where: { id },
-      data: updateData,
+      data: updates,
     })
+    return user
   })
 ```
 
-### DELETE: 데이터 삭제
+### DELETE
 
 ```typescript
-// ✅ DELETE + 인증
-export const deletePost = createServerFn({ method: 'DELETE' })
-  .middleware([authMiddleware])
-  .inputValidator(z.object({ id: z.string() }))
-  .handler(async ({ data, context }) => {
-    // 권한 체크
-    const post = await prisma.post.findUnique({
-      where: { id: data.id },
-    })
-
-    if (post?.authorId !== context.user.id) {
-      throw new Error('Unauthorized')
-    }
+// app/functions/users.ts
+const deleteUserSchema = z.object({
+  id: z.string().uuid(),
+})
 
-    return prisma.post.delete({
-      where: { id: data.id },
-    })
+export const deleteUser = createServerFn({ method: 'DELETE' })
+  .inputValidator(deleteUserSchema)
+  .middleware([authMiddleware, adminMiddleware])
+  .handler(async ({ data }) => {
+    await db.user.delete({ where: { id: data.id } })
+    return { success: true }
   })
 ```
 
-### 클라이언트에서 호출 (TanStack Query 필수)
+## Client에서 호출 (TanStack Query)
 
-```tsx
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+### useSuspenseQuery (GET)
 
-// ✅ useQuery (조회)
-const UsersPage = (): JSX.Element => {
-  const { data, isLoading, error } = useQuery({
-    queryKey: ['users'],
-    queryFn: () => getUsers(),
-  })
+```typescript
+// app/routes/users.$userId.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { useSuspenseQuery } from '@tanstack/react-query'
+import { getUser } from '~/functions/users'
+
+export const Route = createFileRoute('/users/$userId')({
+  component: UserDetail,
+})
+
+function UserDetail() {
+  const { userId } = Route.useParams()
 
-  if (isLoading) return <div>Loading...</div>
-  if (error) return <div>Error: {error.message}</div>
+  const { data: user } = useSuspenseQuery({
+    queryKey: ['user', userId],
+    queryFn: () => getUser({ data: { id: userId } }),
+  })
 
   return (
-    <ul>
-      {data?.map((user) => (
-        <li key={user.id}>{user.name}</li>
-      ))}
-    </ul>
+    <div>
+      <h1>{user.name}</h1>
+      <p>{user.email}</p>
+    </div>
   )
 }
+```
+
+### useMutation (POST/PUT/DELETE)
+
+```typescript
+// app/routes/users.new.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { createUser } from '~/functions/users'
 
-// ✅ useMutation (생성/수정/삭제)
-const CreateUserForm = (): JSX.Element => {
+export const Route = createFileRoute('/users/new')({
+  component: NewUser,
+})
+
+function NewUser() {
   const queryClient = useQueryClient()
+  const navigate = Route.useNavigate()
 
   const mutation = useMutation({
     mutationFn: createUser,
-    onSuccess: () => {
-      // 캐시 무효화 → 자동 리페치
+    onSuccess: (user) => {
       queryClient.invalidateQueries({ queryKey: ['users'] })
+      navigate({ to: '/users/$userId', params: { userId: user.id } })
     },
   })
 
@@ -309,96 +367,123 @@ const CreateUserForm = (): JSX.Element => {
     const formData = new FormData(e.currentTarget)
 
     mutation.mutate({
-      email: formData.get('email') as string,
-      name: formData.get('name') as string,
+      data: {
+        email: formData.get('email') as string,
+        name: formData.get('name') as string,
+      },
     })
   }
 
   return (
     <form onSubmit={handleSubmit}>
       <input name="email" type="email" required />
-      <input name="name" required />
+      <input name="name" type="text" required />
       <button type="submit" disabled={mutation.isPending}>
-        {mutation.isPending ? 'Creating...' : 'Create'}
+        {mutation.isPending ? 'Creating...' : 'Create User'}
       </button>
-      {mutation.error && <p>Error: {mutation.error.message}</p>}
+      {mutation.isError && <p>Error: {mutation.error.message}</p>}
     </form>
   )
 }
+```
 
-// ❌ 직접 호출 금지 (캐싱 없음, 동기화 안됨)
-const BadComponent = (): JSX.Element => {
-  const [users, setUsers] = useState([])
-
-  useEffect(() => {
-    getUsers().then(setUsers) // ❌ 직접 호출
-  }, [])
+## Helper Functions 패턴
 
-  return <div>{/* ... */}</div>
-}
-```
+**규칙**: 민감한 로직(DB 쿼리, 인증, 비즈니스 로직)은 Server Function 외부에 분리
 
-### 함수 분리 규칙
+### ✅ 올바른 패턴
 
 ```typescript
-// ❌ 잘못된 구조: 헬퍼 함수 export
-export const validateUserData = async (email: string) => {
-  const exists = await prisma.user.findUnique({ where: { email } })
-  if (exists) throw new Error('Email already exists')
+// app/functions/users-helpers.ts
+import 'server-only' // Ensures this file is never bundled for client
+
+export async function getUserFromDB(id: string) {
+  const user = await db.user.findUnique({ where: { id } })
+  if (!user) throw new Error('User not found')
+  return user
 }
 
+export async function createUserInDB(data: {
+  email: string
+  name: string
+  passwordHash: string
+}) {
+  return db.user.create({ data })
+}
+
+// app/functions/users.ts
+import { createServerFn } from '@tanstack/react-start'
+import { getUserFromDB, createUserInDB } from './users-helpers'
+
+export const getUser = createServerFn({ method: 'GET' })
+  .inputValidator(getUserSchema)
+  .handler(async ({ data }) => getUserFromDB(data.id))
+
 export const createUser = createServerFn({ method: 'POST' })
   .inputValidator(createUserSchema)
+  .middleware([authMiddleware])
   .handler(async ({ data }) => {
-    await validateUserData(data.email) // ❌ export된 헬퍼 사용
-    return prisma.user.create({ data })
+    const passwordHash = await hashPassword(data.password)
+    return createUserInDB({ ...data, passwordHash })
   })
+```
 
-// ✅ 올바른 구조: 헬퍼는 export 금지
-const validateUserData = async (email: string) => {
-  const exists = await prisma.user.findUnique({ where: { email } })
-  if (exists) throw new Error('Email already exists')
-}
+### ❌ 잘못된 패턴
 
-export const createUser = createServerFn({ method: 'POST' })
-  .inputValidator(createUserSchema)
+```typescript
+// ❌ Server Function 내부에 직접 DB 로직
+export const getUser = createServerFn({ method: 'GET' })
+  .inputValidator(getUserSchema)
   .handler(async ({ data }) => {
-    await validateUserData(data.email) // ✅ 내부 헬퍼만 사용
-    return prisma.user.create({ data })
+    // ❌ 민감 로직이 클라이언트 번들에 포함될 수 있음
+    const user = await db.user.findUnique({ where: { id: data.id } })
+    return user
   })
-
-// index.ts: Server Function만 export
-export { getUsers, createUser, updateUser } from './user-functions'
-// ❌ export { validateUserData } 금지
 ```
 
-### 보안: 환경 변수
+## Environment Variables 보안
 
 ```typescript
-// ❌ loader에서 환경변수 직접 사용 (클라이언트 노출)
-export const Route = createFileRoute('/config')({
-  loader: () => {
-    const secret = process.env.API_SECRET // ❌ 클라이언트에 노출됨!
-    return { secret }
-  },
-  component: ConfigPage,
+// ✅ Helper function에서 env 사용
+// app/functions/stripe-helpers.ts
+import 'server-only'
+import Stripe from 'stripe'
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2023-10-16',
 })
 
-// ✅ Server Function에서만 사용
-const getConfig = createServerFn({ method: 'GET' })
+export async function createPaymentIntent(amount: number) {
+  return stripe.paymentIntents.create({
+    amount,
+    currency: 'usd',
+  })
+}
+
+// app/functions/stripe.ts
+import { createServerFn } from '@tanstack/react-start'
+import { createPaymentIntent } from './stripe-helpers'
+
+export const createPayment = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ amount: z.number().positive() }))
   .middleware([authMiddleware])
+  .handler(async ({ data }) => createPaymentIntent(data.amount))
+```
+
+## Static Server Functions (Experimental)
+
+정적 사이트 생성 시 Server Functions를 빌드 타임에 실행:
+
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+import { staticFunctionMiddleware } from '@tanstack/react-start/static'
+
+export const getStaticPosts = createServerFn({ method: 'GET' })
+  .middleware([staticFunctionMiddleware])
   .handler(async () => {
-    const secret = process.env.API_SECRET // ✅ 서버에서만 실행
-    return { secret }
+    const posts = await fetchAllPosts()
+    return posts
   })
-
-export const Route = createFileRoute('/config')({
-  loader: async () => {
-    const config = await getConfig()
-    return config
-  },
-  component: ConfigPage,
-})
 ```
 
 </server_functions>
@@ -407,189 +492,272 @@ export const Route = createFileRoute('/config')({
 
 <middleware>
 
-## Middleware
-
-Server Function 및 라우트에 공통 로직 적용.
+## Middleware 개요
 
-### 기본 패턴
-
-```typescript
-// 미들웨어 정의
-const loggingMiddleware = createMiddleware({ type: 'function' })
-  .server(({ next }) => {
-    console.log('Processing request')
-    return next()
-  })
+Middleware는 Server Functions와 Routes에서 재사용 가능한 로직을 제공합니다.
 
-// Server Function에 적용
-const fn = createServerFn({ method: 'GET' })
-  .middleware([loggingMiddleware])
-  .handler(async () => ({ message: 'Hello' }))
-```
+**사용 사례**:
+- 인증/인가
+- 입력 검증
+- 로깅
+- Rate limiting
+- CORS 설정
 
-### 인증 미들웨어
+## createMiddleware
 
 ```typescript
-// 세션 기반 인증
-const authMiddleware = createMiddleware({ type: 'function' })
-  .server(async ({ next }) => {
-    const session = await getSession()
-    if (!session?.user) {
-      throw redirect({ to: '/login' })
-    }
-    return next({ context: { user: session.user } })
-  })
+// app/middleware/auth.ts
+import { createMiddleware } from '@tanstack/react-start'
+import { getSessionFromCookie } from '~/auth-helpers'
 
-// Server Function에 적용
-export const getMyPosts = createServerFn({ method: 'GET' })
-  .middleware([authMiddleware])
-  .handler(async ({ context }) => {
-    return prisma.post.findMany({
-      where: { authorId: context.user.id },
-    })
-  })
+export const authMiddleware = createMiddleware().server(async ({ next }) => {
+  const session = await getSessionFromCookie()
 
-// 권한 체크 미들웨어
-const adminMiddleware = createMiddleware({ type: 'function' })
-  .server(async ({ next }) => {
-    const session = await getSession()
-    if (!session?.user || session.user.role !== 'ADMIN') {
-      throw new Error('Forbidden: Admin only')
-    }
-    return next({ context: { user: session.user } })
-  })
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
 
-// 적용
-export const deleteAnyPost = createServerFn({ method: 'DELETE' })
-  .middleware([adminMiddleware])
-  .inputValidator(z.object({ id: z.string() }))
-  .handler(async ({ data }) => {
-    return prisma.post.delete({ where: { id: data.id } })
+  return next({
+    context: {
+      user: session.user,
+      sessionId: session.id,
+    },
   })
+})
 ```
 
-### Zod Validation Middleware
+## Zod Validation Middleware
 
 ```typescript
-// 재사용 가능한 검증 미들웨어
-const workspaceMiddleware = createMiddleware({ type: 'function' })
-  .inputValidator(z.object({ workspaceId: z.string() }))
-  .server(async ({ next, data }) => {
-    const workspace = await prisma.workspace.findUnique({
-      where: { id: data.workspaceId },
-    })
+// app/middleware/validation.ts
+import { createMiddleware } from '@tanstack/react-start'
+import { z } from 'zod'
 
-    if (!workspace) {
-      throw new Error('Workspace not found')
-    }
+export const createValidationMiddleware = <T extends z.ZodType>(
+  schema: T
+) => {
+  return createMiddleware().server(async ({ next, data }) => {
+    const validated = schema.parse(data)
 
-    return next({ context: { workspace } })
+    return next({
+      context: {
+        validated: validated as z.infer<T>,
+      },
+    })
   })
+}
+
+// Usage
+const userSchema = z.object({ email: z.email() })
+const validateUser = createValidationMiddleware(userSchema)
 
-// 적용
-export const getWorkspaceData = createServerFn({ method: 'GET' })
-  .middleware([authMiddleware, workspaceMiddleware])
+export const createUser = createServerFn({ method: 'POST' })
+  .middleware([validateUser])
   .handler(async ({ context }) => {
-    return {
-      user: context.user,
-      workspace: context.workspace,
-    }
+    const { validated } = context // Type-safe
+    return db.user.create({ data: validated })
   })
 ```
 
-### 미들웨어 체이닝
+## Middleware Chaining
 
 ```typescript
-// 여러 미들웨어 조합
-export const protectedWorkspaceFn = createServerFn({ method: 'POST' })
-  .middleware([
-    loggingMiddleware,      // 1. 로깅
-    authMiddleware,          // 2. 인증
-    workspaceMiddleware,     // 3. Workspace 검증
-  ])
-  .inputValidator(taskSchema)
-  .handler(async ({ data, context }) => {
-    return prisma.task.create({
-      data: {
-        ...data,
-        workspaceId: context.workspace.id,
-        createdById: context.user.id,
+// app/middleware/admin.ts
+import { createMiddleware } from '@tanstack/react-start'
+
+export const adminMiddleware = createMiddleware().server(
+  async ({ next, context }) => {
+    // authMiddleware에서 context.user 주입됨
+    if (context.user.role !== 'admin') {
+      throw new Error('Forbidden: Admin access required')
+    }
+
+    return next({
+      context: {
+        ...context,
+        isAdmin: true,
       },
     })
+  }
+)
+
+// Usage: authMiddleware → adminMiddleware 순서로 실행
+export const deleteUser = createServerFn({ method: 'DELETE' })
+  .inputValidator(deleteUserSchema)
+  .middleware([authMiddleware, adminMiddleware])
+  .handler(async ({ data, context }) => {
+    console.log(context.isAdmin) // true
+    await db.user.delete({ where: { id: data.id } })
+    return { success: true }
   })
 ```
 
-### Global Middleware
+## Global Middleware
 
 ```typescript
-// src/start.ts
-export const startInstance = createStart(() => ({
-  requestMiddleware: [corsMiddleware],     // 모든 요청
-  functionMiddleware: [loggingMiddleware], // 모든 Server Function
-}))
+// app/router.tsx
+import { createRouter } from '@tanstack/react-router'
+import { loggingMiddleware } from '~/middleware/logging'
+
+export const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent',
+  context: {
+    // Global context
+  },
+  middleware: [loggingMiddleware], // 모든 routes에 적용
+})
 ```
 
-### Route-Level Middleware
+## Route-level Middleware
 
 ```typescript
-// 특정 라우트에만 적용
-export const Route = createFileRoute('/admin/dashboard')({
-  server: {
-    middleware: [adminMiddleware], // 이 라우트의 모든 핸들러에 적용
-    handlers: {
-      GET: async () => new Response('Admin Dashboard'),
-    },
+// app/routes/_authenticated.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { authMiddleware } from '~/middleware/auth'
+
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: async ({ context }) => {
+    // authMiddleware 실행
+    const session = await getSession()
+    if (!session) {
+      throw redirect({ to: '/login' })
+    }
+    return {
+      user: session.user,
+    }
   },
 })
 ```
 
+## Logging Middleware
+
+```typescript
+// app/middleware/logging.ts
+import { createMiddleware } from '@tanstack/react-start'
+
+export const loggingMiddleware = createMiddleware().server(
+  async ({ next, method, url }) => {
+    const start = Date.now()
+
+    console.log(`[${method}] ${url} - Start`)
+
+    try {
+      const result = await next()
+      const duration = Date.now() - start
+      console.log(`[${method}] ${url} - Success (${duration}ms)`)
+      return result
+    } catch (error) {
+      const duration = Date.now() - start
+      console.error(`[${method}] ${url} - Error (${duration}ms)`, error)
+      throw error
+    }
+  }
+)
+```
+
+## Rate Limiting Middleware
+
+```typescript
+// app/middleware/rate-limit.ts
+import { createMiddleware } from '@tanstack/react-start'
+import { Ratelimit } from '@upstash/ratelimit'
+import { Redis } from '@upstash/redis'
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '10 s'),
+})
+
+export const rateLimitMiddleware = createMiddleware().server(
+  async ({ next, context }) => {
+    const identifier = context.user?.id || 'anonymous'
+    const { success } = await ratelimit.limit(identifier)
+
+    if (!success) {
+      throw new Error('Rate limit exceeded')
+    }
+
+    return next()
+  }
+)
+```
+
 </middleware>
 
 ---
 
 <routing>
 
-## Routing
+## File-based Routing
 
-File-based routing with TanStack Router.
+TanStack Start는 `app/routes/` 디렉토리 구조를 URL로 변환합니다.
 
 ### 파일 구조 → URL 매핑
 
-| 파일 경로 | URL | 설명 |
-|----------|-----|------|
-| `routes/index.tsx` | `/` | 홈 페이지 |
-| `routes/about.tsx` | `/about` | 정적 라우트 |
-| `routes/users/$id.tsx` | `/users/:id` | 동적 파라미터 |
-| `routes/users/index.tsx` | `/users` | 사용자 목록 |
-| `routes/$.tsx` | `/*` | Catch-all (404) |
-| `routes/__root.tsx` | - | Root layout |
+| 파일 경로 | URL |
+|-----------|-----|
+| `routes/index.tsx` | `/` |
+| `routes/about.tsx` | `/about` |
+| `routes/posts.index.tsx` | `/posts` |
+| `routes/posts.$postId.tsx` | `/posts/:postId` |
+| `routes/posts.$postId.edit.tsx` | `/posts/:postId/edit` |
+| `routes/blog._layout.tsx` | Layout (no URL) |
+| `routes/blog._layout.posts.tsx` | `/blog/posts` |
+| `routes/admin._.tsx` | `/admin/*` (catch-all) |
+
+## Basic Routes
+
+### Index Route
+
+```typescript
+// app/routes/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/')({
+  component: Home,
+})
+
+function Home() {
+  return (
+    <div>
+      <h1>Welcome to TanStack Start</h1>
+    </div>
+  )
+}
+```
+
+### Static Route
 
-### 기본 라우트
+```typescript
+// app/routes/about.tsx
+import { createFileRoute } from '@tanstack/react-router'
 
-```tsx
-// routes/about.tsx
 export const Route = createFileRoute('/about')({
-  component: AboutPage,
+  component: About,
 })
 
-const AboutPage = (): JSX.Element => {
+function About() {
   return <div>About Page</div>
 }
 ```
 
-### Loader: 데이터 사전 로드
+## Loader Pattern
+
+```typescript
+// app/routes/posts.index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { getPosts } from '~/functions/posts'
 
-```tsx
-// routes/posts/index.tsx
-export const Route = createFileRoute('/posts')({
-  component: PostsPage,
+export const Route = createFileRoute('/posts/')({
   loader: async () => {
     const posts = await getPosts()
     return { posts }
   },
+  component: PostsList,
 })
 
-const PostsPage = (): JSX.Element => {
+function PostsList() {
   const { posts } = Route.useLoaderData()
 
   return (
@@ -602,767 +770,1243 @@ const PostsPage = (): JSX.Element => {
 }
 ```
 
-### 동적 라우트
+## Dynamic Routes
+
+### Path Parameters
 
-```tsx
-// routes/users/$id.tsx
-export const Route = createFileRoute('/users/$id')({
+```typescript
+// app/routes/posts.$postId.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { getPost } from '~/functions/posts'
+
+export const Route = createFileRoute('/posts/$postId')({
   loader: async ({ params }) => {
-    const user = await getUserById(params.id)
-    return { user }
+    const post = await getPost({ data: { id: params.postId } })
+    return { post }
   },
-  component: UserPage,
+  component: PostDetail,
 })
 
-const UserPage = (): JSX.Element => {
-  const { user } = Route.useLoaderData()
+function PostDetail() {
+  const { postId } = Route.useParams()
+  const { post } = Route.useLoaderData()
 
   return (
-    <div>
-      <h1>{user.name}</h1>
-      <p>{user.email}</p>
-    </div>
+    <article>
+      <h1>{post.title}</h1>
+      <p>{post.content}</p>
+    </article>
   )
 }
 ```
 
-### SSR 옵션
-
-| 옵션 | 동작 | 사용 시점 |
-|------|------|----------|
-| `ssr: true` | 전체 SSR (기본값) | 일반 페이지 |
-| `ssr: false` | 클라이언트만 렌더링 | 인증 필요 페이지 |
-| `ssr: 'data-only'` | 데이터만 서버에서 로드 | 데이터 + 클라이언트 렌더링 |
-
-```tsx
-// ssr 옵션 예시
-export const Route = createFileRoute('/dashboard')({
-  ssr: false, // 클라이언트에서만 렌더링
-  component: DashboardPage,
-})
-```
+### Search Parameters
 
-### beforeLoad: 라우트 접근 전 체크
+```typescript
+// app/routes/search.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
 
-```tsx
-// routes/dashboard.tsx
-export const Route = createFileRoute('/dashboard')({
-  beforeLoad: async () => {
-    const user = await getCurrentUser()
-    if (!user) {
-      throw redirect({ to: '/login' })
-    }
-    return { user }
-  },
-  component: DashboardPage,
+const searchSchema = z.object({
+  q: z.string().optional(),
+  page: z.number().int().positive().default(1),
+  sort: z.enum(['asc', 'desc']).default('asc'),
 })
 
-const DashboardPage = (): JSX.Element => {
-  const { user } = Route.useRouteContext()
-  return <h1>Welcome, {user.name}!</h1>
-}
-```
-
-### Server Routes (API 엔드포인트)
-
-```tsx
-// routes/api/hello.tsx
-export const Route = createFileRoute('/api/hello')({
-  server: {
-    handlers: {
-      GET: async () => {
-        return new Response('Hello World')
-      },
-      POST: async ({ request }) => {
-        const body = await request.json()
-        return Response.json({ name: body.name })
-      },
-    },
+export const Route = createFileRoute('/search')({
+  validateSearch: searchSchema,
+  loaderDeps: ({ search }) => ({ search }),
+  loader: async ({ deps }) => {
+    const results = await searchPosts(deps.search)
+    return { results }
   },
+  component: SearchPage,
 })
-```
 
-### Catch-all Route (404)
+function SearchPage() {
+  const { q, page, sort } = Route.useSearch()
+  const { results } = Route.useLoaderData()
+  const navigate = Route.useNavigate()
 
-```tsx
-// routes/$.tsx
-export const Route = createFileRoute('/$')({
-  component: NotFoundPage,
-})
+  const updateSearch = (newQ: string) => {
+    navigate({
+      search: (prev) => ({ ...prev, q: newQ, page: 1 }),
+    })
+  }
 
-const NotFoundPage = (): JSX.Element => {
   return (
     <div>
-      <h1>404 - Page Not Found</h1>
-      <a href="/">Go Home</a>
+      <input
+        value={q || ''}
+        onChange={(e) => updateSearch(e.target.value)}
+      />
+      <ul>
+        {results.map((result) => (
+          <li key={result.id}>{result.title}</li>
+        ))}
+      </ul>
     </div>
   )
 }
 ```
 
-</routing>
-
----
-
-<auth_patterns>
-
-## 인증 패턴
+## SSR Options
 
-Better Auth 통합 및 인증 패턴.
+```typescript
+// app/routes/posts.$postId.tsx
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost({ data: { id: params.postId } })
+    return { post }
+  },
+  staleTime: 1000 * 60 * 5, // 5분간 캐시
+  gcTime: 1000 * 60 * 10, // 10분 후 가비지 컬렉션
+  shouldReload: false, // 재방문 시 reload 안함
+  component: PostDetail,
+})
+```
+
+**SWR Caching 옵션**:
+| 옵션 | 설명 | 기본값 |
+|------|------|--------|
+| `staleTime` | 데이터가 fresh한 시간 (ms) | 0 |
+| `gcTime` | 메모리에서 제거되기까지 시간 (ms) | 30분 |
+| `shouldReload` | 재방문 시 reload 여부 | true |
 
-### Better Auth 설정
+## beforeLoad (Auth Guard)
 
 ```typescript
-// lib/auth.ts
-import { betterAuth } from 'better-auth'
-import { prismaAdapter } from 'better-auth/adapters/prisma'
-import { prisma } from '@/database/prisma'
+// app/routes/_authenticated.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+import { getSession } from '~/auth-helpers'
 
-export const auth = betterAuth({
-  database: prismaAdapter(prisma),
-  emailAndPassword: { enabled: true },
-  session: {
-    expiresIn: 60 * 60 * 24 * 7, // 7일
-    updateAge: 60 * 60 * 24,      // 1일마다 갱신
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: async ({ context, location }) => {
+    const session = await getSession()
+
+    if (!session) {
+      throw redirect({
+        to: '/login',
+        search: {
+          redirect: location.href,
+        },
+      })
+    }
+
+    return {
+      user: session.user,
+    }
   },
 })
 
-export type Session = typeof auth.$Infer.Session
+// app/routes/_authenticated.profile.tsx
+export const Route = createFileRoute('/_authenticated/profile')({
+  component: Profile,
+})
+
+function Profile() {
+  const { user } = Route.useRouteContext()
+  return <div>Welcome, {user.name}</div>
+}
 ```
 
-### 인증 Server Functions
+## Nested Layouts
 
 ```typescript
-// functions/auth.ts
+// app/routes/_layout.tsx
+import { createFileRoute, Outlet } from '@tanstack/react-router'
 
-// 로그인
-const loginSchema = z.object({
-  email: z.email(),
-  password: z.string().min(8),
+export const Route = createFileRoute('/_layout')({
+  component: Layout,
 })
 
-export const login = createServerFn({ method: 'POST' })
-  .inputValidator(loginSchema)
-  .handler(async ({ data, request }) => {
-    const result = await auth.api.signInEmail({
-      email: data.email,
-      password: data.password,
-      headers: request.headers,
-    })
+function Layout() {
+  return (
+    <div>
+      <nav>Navigation</nav>
+      <main>
+        <Outlet /> {/* Child routes render here */}
+      </main>
+      <footer>Footer</footer>
+    </div>
+  )
+}
 
-    if (!result.user) {
-      throw new Error('Invalid credentials')
-    }
+// app/routes/_layout.page1.tsx
+export const Route = createFileRoute('/_layout/page1')({
+  component: () => <div>Page 1</div>,
+})
 
-    throw redirect({ to: '/dashboard' })
-  })
+// app/routes/_layout.page2.tsx
+export const Route = createFileRoute('/_layout/page2')({
+  component: () => <div>Page 2</div>,
+})
+```
 
-// 로그아웃
-export const logout = createServerFn({ method: 'POST' })
-  .handler(async ({ request }) => {
-    await auth.api.signOut({ headers: request.headers })
-    throw redirect({ to: '/' })
-  })
+## Server Routes (New API)
 
-// 현재 사용자
-export const getCurrentUser = createServerFn({ method: 'GET' })
-  .handler(async ({ request }) => {
-    const session = await auth.api.getSession({
-      headers: request.headers,
-    })
-    return session?.user ?? null
-  })
+**중요**: `createAPIFileRoute()` → `createServerFileRoute()` + `.methods()` 로 변경됨
 
-// 회원가입
-const registerSchema = z.object({
-  email: z.email(),
-  password: z.string().min(8),
-  name: z.string().min(1),
+### RESTful API Endpoint
+
+```typescript
+// app/routes/api/users.$userId.tsx
+import { createServerFileRoute } from '@tanstack/react-start'
+import { z } from 'zod'
+
+const getUserSchema = z.object({
+  userId: z.string().uuid(),
 })
 
-export const register = createServerFn({ method: 'POST' })
-  .inputValidator(registerSchema)
-  .handler(async ({ data, request }) => {
-    const result = await auth.api.signUpEmail({
-      email: data.email,
-      password: data.password,
-      name: data.name,
-      headers: request.headers,
-    })
+const updateUserSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().optional(),
+  email: z.email().optional(),
+})
 
-    if (!result.user) {
-      throw new Error('Registration failed')
-    }
+export const Route = createServerFileRoute('/api/users/$userId')
+  .methods({
+    GET: async ({ request, params }) => {
+      const { userId } = getUserSchema.parse(params)
+      const user = await db.user.findUnique({ where: { id: userId } })
+
+      if (!user) {
+        return new Response('Not Found', { status: 404 })
+      }
 
-    throw redirect({ to: '/dashboard' })
+      return Response.json(user)
+    },
+
+    PUT: async ({ request, params }) => {
+      const body = await request.json()
+      const { userId, ...updates } = updateUserSchema.parse({
+        ...params,
+        ...body,
+      })
+
+      const user = await db.user.update({
+        where: { id: userId },
+        data: updates,
+      })
+
+      return Response.json(user)
+    },
+
+    DELETE: async ({ request, params }) => {
+      const { userId } = getUserSchema.parse(params)
+      await db.user.delete({ where: { id: userId } })
+
+      return Response.json({ success: true })
+    },
   })
 ```
 
-### 인증 미들웨어
+### File Upload Endpoint
 
 ```typescript
-// middleware/auth.ts
-export const authMiddleware = createMiddleware({ type: 'function' })
-  .server(async ({ next, request }) => {
-    const session = await auth.api.getSession({
-      headers: request.headers,
-    })
+// app/routes/api/upload.tsx
+import { createServerFileRoute } from '@tanstack/react-start'
+import { writeFile } from 'fs/promises'
+import { join } from 'path'
 
-    if (!session?.user) {
-      throw redirect({ to: '/login' })
-    }
+export const Route = createServerFileRoute('/api/upload')
+  .methods({
+    POST: async ({ request }) => {
+      const formData = await request.formData()
+      const file = formData.get('file') as File
 
-    return next({ context: { user: session.user } })
+      if (!file) {
+        return new Response('No file provided', { status: 400 })
+      }
+
+      const bytes = await file.arrayBuffer()
+      const buffer = Buffer.from(bytes)
+
+      const path = join(process.cwd(), 'uploads', file.name)
+      await writeFile(path, buffer)
+
+      return Response.json({ success: true, path })
+    },
   })
 ```
 
-### 보호된 Server Function
+## Catch-all Routes
 
 ```typescript
-// functions/posts.ts
-export const getMyPosts = createServerFn({ method: 'GET' })
-  .middleware([authMiddleware])
-  .handler(async ({ context }) => {
-    return prisma.post.findMany({
-      where: { authorId: context.user.id },
-    })
-  })
+// app/routes/docs._.tsx
+import { createFileRoute } from '@tanstack/react-router'
 
-export const createPost = createServerFn({ method: 'POST' })
-  .middleware([authMiddleware])
-  .inputValidator(z.object({
-    title: z.string().min(1),
-    content: z.string().min(1),
-  }))
-  .handler(async ({ data, context }) => {
-    return prisma.post.create({
-      data: {
-        ...data,
-        authorId: context.user.id,
-      },
-    })
-  })
+export const Route = createFileRoute('/docs/$')({
+  component: DocsPage,
+})
+
+function DocsPage() {
+  const params = Route.useParams()
+  const splat = params['_splat'] // Captures everything after /docs/
+
+  return <div>Docs: {splat}</div>
+}
 ```
 
-### 보호된 라우트
+## Link Navigation
 
-```tsx
-// routes/dashboard.tsx
-export const Route = createFileRoute('/dashboard')({
-  beforeLoad: async () => {
-    const user = await getCurrentUser()
-    if (!user) {
-      throw redirect({ to: '/login' })
-    }
-    return { user }
+```typescript
+import { Link } from '@tanstack/react-router'
+
+function Navigation() {
+  return (
+    <nav>
+      <Link to="/">Home</Link>
+      <Link to="/about">About</Link>
+      <Link
+        to="/posts/$postId"
+        params={{ postId: '123' }}
+      >
+        Post 123
+      </Link>
+      <Link
+        to="/search"
+        search={{ q: 'tanstack', page: 1 }}
+      >
+        Search
+      </Link>
+    </nav>
+  )
+}
+```
+
+## Preload Strategy
+
+```typescript
+// app/routes/posts.$postId.tsx
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost({ data: { id: params.postId } })
+    return { post }
   },
-  component: DashboardPage,
+  component: PostDetail,
 })
 
-const DashboardPage = (): JSX.Element => {
-  const { user } = Route.useRouteContext()
-
+// Usage
+function PostsList() {
   return (
     <div>
-      <h1>Welcome, {user.name}!</h1>
+      {posts.map((post) => (
+        <Link
+          key={post.id}
+          to="/posts/$postId"
+          params={{ postId: post.id }}
+          preload="intent" // Preload on hover/focus
+        >
+          {post.title}
+        </Link>
+      ))}
     </div>
   )
 }
 ```
 
-### 로그인 폼 (TanStack Query)
+**Preload 옵션**:
+| 값 | 동작 |
+|----|------|
+| `false` | Preload 안함 |
+| `intent` | Hover/focus 시 preload |
+| `render` | Link 렌더링 시 preload |
+| `viewport` | Viewport 진입 시 preload |
 
-```tsx
-// routes/login.tsx
-const LoginPage = (): JSX.Element => {
-  const mutation = useMutation({
-    mutationFn: login,
-  })
+## Pending Component
 
-  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
-    e.preventDefault()
-    const formData = new FormData(e.currentTarget)
+```typescript
+// app/routes/posts.$postId.tsx
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    await delay(2000) // Simulate slow loading
+    const post = await getPost({ data: { id: params.postId } })
+    return { post }
+  },
+  pendingComponent: () => <div>Loading post...</div>,
+  component: PostDetail,
+})
+```
 
-    mutation.mutate({
-      email: formData.get('email') as string,
-      password: formData.get('password') as string,
-    })
-  }
+## Error Boundaries
 
-  return (
-    <form onSubmit={handleSubmit}>
-      <input name="email" type="email" required />
-      <input name="password" type="password" required />
-      <button type="submit" disabled={mutation.isPending}>
-        {mutation.isPending ? 'Logging in...' : 'Login'}
-      </button>
-      {mutation.error && <p>Error: {mutation.error.message}</p>}
-    </form>
-  )
-}
+```typescript
+// app/routes/posts.$postId.tsx
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost({ data: { id: params.postId } })
+    if (!post) {
+      throw new Error('Post not found')
+    }
+    return { post }
+  },
+  errorComponent: ({ error }) => (
+    <div>
+      <h1>Error</h1>
+      <p>{error.message}</p>
+    </div>
+  ),
+  component: PostDetail,
+})
 ```
 
-</auth_patterns>
+## Router Context
 
----
+```typescript
+// app/router.tsx
+import { createRouter } from '@tanstack/react-router'
+import { QueryClient } from '@tanstack/react-query'
 
-<file_structure>
+const queryClient = new QueryClient()
 
-## 파일 구조
-
-### 디렉터리 레이아웃
-
-```
-src/
-├── routes/                 # File-based routes
-│   ├── __root.tsx         # Root layout (모든 라우트의 부모)
-│   ├── index.tsx          # / (홈)
-│   ├── about.tsx          # /about
-│   ├── users/
-│   │   ├── index.tsx      # /users
-│   │   ├── $id.tsx        # /users/:id
-│   │   ├── -components/   # 페이지 전용 컴포넌트 (필수)
-│   │   │   └── user-card.tsx
-│   │   ├── -hooks/        # 페이지 전용 Custom Hooks (필수)
-│   │   │   └── use-user-data.ts
-│   │   └── -functions/    # 페이지 전용 Server Functions (필수)
-│   │       └── user-mutations.ts
-│   └── dashboard/
-│       ├── index.tsx
-│       ├── -components/
-│       ├── -hooks/
-│       └── -functions/
-│
-├── functions/             # 공통 Server Functions
-│   ├── auth.ts
-│   ├── posts.ts
-│   └── users.ts
-│
-├── middleware/            # 공통 Middleware
-│   ├── auth.ts
-│   └── logging.ts
-│
-├── components/            # 공통 컴포넌트
-│   └── ui/
-│       ├── button.tsx
-│       └── input.tsx
-│
-├── lib/                   # 유틸리티
-│   ├── env.ts
-│   └── utils.ts
-│
-└── database/              # Prisma
-    └── prisma.ts
+export const router = createRouter({
+  routeTree,
+  context: {
+    queryClient,
+  },
+  defaultPreload: 'intent',
+  defaultStaleTime: 1000 * 60 * 5, // 5분
+})
+
+// app/routes/posts.$postId.tsx
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params, context }) => {
+    const post = await context.queryClient.ensureQueryData({
+      queryKey: ['post', params.postId],
+      queryFn: () => getPost({ data: { id: params.postId } }),
+    })
+    return { post }
+  },
+  component: PostDetail,
+})
 ```
 
-### 파일 분리 규칙
+## Streaming SSR
 
-| 위치 | 사용 시점 | 예시 |
-|------|----------|------|
-| `routes/[path]/-components/` | 해당 페이지에서만 사용 | `user-card.tsx` |
-| `routes/[path]/-hooks/` | 해당 페이지 전용 Hook | `use-user-data.ts` |
-| `routes/[path]/-functions/` | 해당 페이지 전용 Server Function | `user-mutations.ts` |
-| `@/functions/` | 여러 페이지에서 재사용 | `auth.ts`, `posts.ts` |
-| `@/components/` | 공통 UI 컴포넌트 | `button.tsx`, `input.tsx` |
-| `@/middleware/` | 공통 미들웨어 | `auth.ts`, `logging.ts` |
+```typescript
+// app/routes/dashboard.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { Suspense } from 'react'
 
-### 필수 규칙
+export const Route = createFileRoute('/dashboard')({
+  component: Dashboard,
+})
 
-✅ **페이지당 `-components/`, `-hooks/`, `-functions/` 폴더 필수**
-- Custom Hook은 페이지 크기와 무관하게 **반드시** `-hooks/` 폴더에 분리
-- 줄 수 무관: 10줄이든 100줄이든 분리 필수
+function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <Suspense fallback={<div>Loading analytics...</div>}>
+        <AnalyticsPanel />
+      </Suspense>
+      <Suspense fallback={<div>Loading activity...</div>}>
+        <ActivityFeed />
+      </Suspense>
+    </div>
+  )
+}
 
-✅ **공통 함수 → `@/functions/`**
-- 여러 페이지에서 사용하는 Server Function
+function AnalyticsPanel() {
+  const { data } = useSuspenseQuery({
+    queryKey: ['analytics'],
+    queryFn: () => getAnalytics(),
+  })
+  return <div>{/* Render analytics */}</div>
+}
+```
 
-✅ **라우트 전용 → `routes/[경로]/-functions/`**
-- 해당 라우트에서만 사용하는 Server Function
+</routing>
 
-❌ **index.ts에서 내부 헬퍼 함수 export 금지**
-- Server Function만 export
+---
 
-</file_structure>
+<auth_patterns>
 
----
+## Better Auth 통합
 
-<dos_donts>
+Better Auth는 TanStack Start와 완벽하게 호환되는 인증 라이브러리입니다.
 
-## Do's & Don'ts
+### 설치 및 설정
 
-### Server Functions
+```bash
+npm install better-auth
+```
 
-| ✅ Do | ❌ Don't |
-|-------|----------|
-| `createServerFn({ method: 'POST' })` 사용 | 일반 async 함수를 API로 사용 |
-| POST/PUT/PATCH에 `.inputValidator()` 필수 | handler 내부에서 수동 검증 |
-| 인증 필요 시 `.middleware([authMiddleware])` | handler 내부에서 세션 체크 |
-| `.inputValidator(zodSchema)` 사용 (v1) | `.validator()` 사용 (deprecated) |
-| 명시적 return type 선언 | any 타입 사용 |
-| 내부 헬퍼는 export 금지 | 헬퍼 함수 export |
-| Server Function에서만 `process.env` 사용 | loader에서 환경변수 직접 사용 |
+```typescript
+// app/auth.ts
+import { betterAuth } from 'better-auth'
+import { prismaAdapter } from 'better-auth/adapters/prisma'
+import { prisma } from '~/db'
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma, {
+    provider: 'postgresql',
+  }),
+  emailAndPassword: {
+    enabled: true,
+  },
+  socialProviders: {
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    },
+  },
+})
+```
 
-### 예시: Server Functions
+### Auth Server Functions
 
 ```typescript
-// ✅ 올바른 패턴
-const schema = z.object({
+// app/functions/auth.ts
+import { createServerFn } from '@tanstack/react-start'
+import { z } from 'zod'
+import { auth } from '~/auth'
+
+const signUpSchema = z.object({
   email: z.email(),
-  name: z.string().min(1),
+  password: z.string().min(8),
+  name: z.string().min(2),
 })
 
-export const createUser = createServerFn({ method: 'POST' })
-  .middleware([authMiddleware])
-  .inputValidator(schema)
-  .handler(async ({ data, context }): Promise<User> => {
-    return prisma.user.create({
-      data: {
-        ...data,
-        createdBy: context.user.id,
-      },
+export const signUp = createServerFn({ method: 'POST' })
+  .inputValidator(signUpSchema)
+  .handler(async ({ data }) => {
+    const user = await auth.api.signUpEmail({
+      email: data.email,
+      password: data.password,
+      name: data.name,
+    })
+    return user
+  })
+
+const signInSchema = z.object({
+  email: z.email(),
+  password: z.string(),
+})
+
+export const signIn = createServerFn({ method: 'POST' })
+  .inputValidator(signInSchema)
+  .handler(async ({ data }) => {
+    const session = await auth.api.signInEmail({
+      email: data.email,
+      password: data.password,
     })
+    return session
   })
 
-// ❌ 잘못된 패턴
-export const badCreate = async (data: any) => { // ❌ createServerFn 없음, any 타입
-  // ❌ 수동 검증
-  if (!data.email || !data.name) {
-    throw new Error('Invalid data')
+export const signOut = createServerFn({ method: 'POST' }).handler(
+  async () => {
+    await auth.api.signOut()
+    return { success: true }
   }
+)
+
+export const getSession = createServerFn({ method: 'GET' }).handler(
+  async () => {
+    const session = await auth.api.getSession()
+    return session
+  }
+)
+```
+
+### Auth Middleware
+
+```typescript
+// app/middleware/auth.ts
+import { createMiddleware } from '@tanstack/react-start'
+import { auth } from '~/auth'
+
+export const authMiddleware = createMiddleware().server(async ({ next }) => {
+  const session = await auth.api.getSession()
 
-  // ❌ 수동 인증 체크
-  const session = await getSession()
   if (!session) {
     throw new Error('Unauthorized')
   }
 
-  return prisma.user.create({ data })
-}
+  return next({
+    context: {
+      user: session.user,
+      sessionId: session.session.id,
+    },
+  })
+})
+
+export const adminMiddleware = createMiddleware().server(
+  async ({ next, context }) => {
+    // Requires authMiddleware to run first
+    if (context.user.role !== 'admin') {
+      throw new Error('Forbidden: Admin access required')
+    }
+
+    return next({
+      context: {
+        ...context,
+        isAdmin: true,
+      },
+    })
+  }
+)
 ```
 
-### 클라이언트 호출
+### Protected Routes
 
-| ✅ Do | ❌ Don't |
-|-------|----------|
-| TanStack Query 사용 (`useQuery`/`useMutation`) | Server Function 직접 호출 |
-| `queryClient.invalidateQueries()` 로 동기화 | 수동 상태 관리 |
-| `isLoading`, `error` 상태 활용 | try-catch로 에러 처리 |
-| `queryKey`로 캐싱 관리 | useEffect + useState |
+```typescript
+// app/routes/_authenticated.tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+import { getSession } from '~/functions/auth'
 
-### 예시: 클라이언트 호출
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: async ({ context, location }) => {
+    const session = await getSession()
 
-```tsx
-// ✅ 올바른 패턴 (useQuery)
-const UsersPage = (): JSX.Element => {
-  const { data, isLoading, error } = useQuery({
-    queryKey: ['users'],
-    queryFn: () => getUsers(),
-  })
+    if (!session) {
+      throw redirect({
+        to: '/login',
+        search: {
+          redirect: location.href,
+        },
+      })
+    }
 
-  if (isLoading) return <div>Loading...</div>
-  if (error) return <div>Error: {error.message}</div>
+    return {
+      user: session.user,
+    }
+  },
+})
+
+// app/routes/_authenticated.profile.tsx
+export const Route = createFileRoute('/_authenticated/profile')({
+  component: Profile,
+})
+
+function Profile() {
+  const { user } = Route.useRouteContext()
 
-  return <ul>{data?.map(u => <li key={u.id}>{u.name}</li>)}</ul>
+  return (
+    <div>
+      <h1>Profile</h1>
+      <p>Email: {user.email}</p>
+      <p>Name: {user.name}</p>
+    </div>
+  )
 }
 
-// ✅ 올바른 패턴 (useMutation)
-const CreateForm = (): JSX.Element => {
+// app/routes/_authenticated.settings.tsx
+export const Route = createFileRoute('/_authenticated/settings')({
+  component: Settings,
+})
+
+function Settings() {
+  const { user } = Route.useRouteContext()
   const queryClient = useQueryClient()
 
-  const mutation = useMutation({
-    mutationFn: createUser,
+  const signOutMutation = useMutation({
+    mutationFn: signOut,
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['users'] })
+      queryClient.clear()
+      window.location.href = '/login'
     },
   })
 
   return (
-    <form onSubmit={(e) => {
-      e.preventDefault()
-      const formData = new FormData(e.currentTarget)
-      mutation.mutate({
-        email: formData.get('email') as string,
-        name: formData.get('name') as string,
-      })
-    }}>
-      <input name="email" type="email" />
-      <input name="name" />
-      <button type="submit">Create</button>
-    </form>
+    <div>
+      <h1>Settings</h1>
+      <p>Logged in as {user.email}</p>
+      <button onClick={() => signOutMutation.mutate()}>
+        Sign Out
+      </button>
+    </div>
   )
 }
+```
 
-// ❌ 잘못된 패턴
-const BadComponent = (): JSX.Element => {
-  const [users, setUsers] = useState([])
-  const [loading, setLoading] = useState(false)
+### Login Form
 
-  useEffect(() => {
-    setLoading(true)
-    getUsers() // ❌ 직접 호출 (캐싱 없음)
-      .then(setUsers)
-      .catch(console.error)
-      .finally(() => setLoading(false))
-  }, [])
+```typescript
+// app/routes/login.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { useMutation } from '@tanstack/react-query'
+import { signIn } from '~/functions/auth'
+import { z } from 'zod'
 
-  return <div>{/* ... */}</div>
-}
-```
+const searchSchema = z.object({
+  redirect: z.string().optional(),
+})
+
+export const Route = createFileRoute('/login')({
+  validateSearch: searchSchema,
+  component: Login,
+})
 
-### Middleware
+function Login() {
+  const { redirect } = Route.useSearch()
+  const navigate = Route.useNavigate()
 
-| ✅ Do | ❌ Don't |
-|-------|----------|
-| 인증/권한 체크를 미들웨어로 분리 | handler 내부에서 체크 |
-| `context`로 데이터 전달 | 전역 변수 사용 |
-| 여러 미들웨어 체이닝 가능 | 하나의 미들웨어에 모든 로직 |
+  const signInMutation = useMutation({
+    mutationFn: signIn,
+    onSuccess: () => {
+      window.location.href = redirect || '/'
+    },
+  })
 
-### 예시: Middleware
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault()
+    const formData = new FormData(e.currentTarget)
+
+    signInMutation.mutate({
+      data: {
+        email: formData.get('email') as string,
+        password: formData.get('password') as string,
+      },
+    })
+  }
+
+  return (
+    <div>
+      <h1>Login</h1>
+      <form onSubmit={handleSubmit}>
+        <input
+          name="email"
+          type="email"
+          placeholder="Email"
+          required
+        />
+        <input
+          name="password"
+          type="password"
+          placeholder="Password"
+          required
+        />
+        <button type="submit" disabled={signInMutation.isPending}>
+          {signInMutation.isPending ? 'Signing in...' : 'Sign In'}
+        </button>
+        {signInMutation.isError && (
+          <p>Error: {signInMutation.error.message}</p>
+        )}
+      </form>
+    </div>
+  )
+}
+```
+
+### Role-based Access Control
 
 ```typescript
-// ✅ 올바른 패턴
-const authMiddleware = createMiddleware({ type: 'function' })
-  .server(async ({ next }) => {
-    const session = await getSession()
-    if (!session) throw redirect({ to: '/login' })
-    return next({ context: { user: session.user } })
-  })
+// app/functions/admin.ts
+import { createServerFn } from '@tanstack/react-start'
+import { authMiddleware, adminMiddleware } from '~/middleware/auth'
 
-export const fn = createServerFn({ method: 'GET' })
-  .middleware([authMiddleware])
+export const getAdminStats = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware, adminMiddleware])
   .handler(async ({ context }) => {
-    return { user: context.user }
+    const stats = await db.stats.findMany()
+    return stats
   })
 
-// ❌ 잘못된 패턴
-export const badFn = createServerFn({ method: 'GET' })
-  .handler(async () => {
-    // ❌ handler 내부에서 인증 체크
-    const session = await getSession()
-    if (!session) throw redirect({ to: '/login' })
-
-    return { user: session.user }
+export const deleteUser = createServerFn({ method: 'DELETE' })
+  .inputValidator(z.object({ userId: z.string().uuid() }))
+  .middleware([authMiddleware, adminMiddleware])
+  .handler(async ({ data }) => {
+    await db.user.delete({ where: { id: data.userId } })
+    return { success: true }
   })
+
+// app/routes/_authenticated._admin.dashboard.tsx
+export const Route = createFileRoute('/_authenticated/_admin/dashboard')({
+  beforeLoad: async ({ context }) => {
+    if (context.user.role !== 'admin') {
+      throw redirect({ to: '/' })
+    }
+  },
+  loader: async () => {
+    const stats = await getAdminStats()
+    return { stats }
+  },
+  component: AdminDashboard,
+})
+
+function AdminDashboard() {
+  const { stats } = Route.useLoaderData()
+  return <div>{/* Render admin dashboard */}</div>
+}
 ```
 
-### 파일 구조
+</auth_patterns>
 
-| ✅ Do | ❌ Don't |
-|-------|----------|
-| 페이지 전용: `routes/[path]/-functions/` | 모든 함수를 `@/functions/`에 |
-| 공통 함수: `@/functions/` | 라우트 파일에 함수 직접 작성 |
-| Custom Hook: `-hooks/` 폴더에 분리 (필수) | 라우트 파일에 Hook 작성 |
+---
 
-### 예시: 파일 구조
+<file_structure>
 
-```typescript
-// ✅ 올바른 구조
-// routes/users/-functions/user-mutations.ts
-export const createUser = createServerFn({ method: 'POST' })
-  .inputValidator(schema)
-  .handler(async ({ data }) => prisma.user.create({ data }))
+## 권장 디렉토리 구조
 
-// routes/users/-hooks/use-user-form.ts
-export const useUserForm = () => {
-  const mutation = useMutation({ mutationFn: createUser })
-  return { mutation }
-}
+```
+app/
+├── routes/
+│   ├── __root.tsx
+│   ├── index.tsx
+│   ├── about.tsx
+│   ├── posts.index.tsx
+│   ├── posts.$postId.tsx
+│   ├── posts.$postId.edit.tsx
+│   ├── _authenticated.tsx
+│   ├── _authenticated.profile.tsx
+│   └── api/
+│       └── users.$userId.tsx
+├── components/
+│   ├── ui/
+│   │   ├── Button.tsx
+│   │   └── Input.tsx
+│   └── PostCard.tsx
+├── functions/
+│   ├── posts.ts
+│   ├── posts-helpers.ts
+│   ├── users.ts
+│   └── auth.ts
+├── middleware/
+│   ├── auth.ts
+│   ├── logging.ts
+│   └── validation.ts
+├── hooks/
+│   ├── useUser.ts
+│   └── usePosts.ts
+├── lib/
+│   ├── db.ts
+│   ├── auth.ts
+│   └── utils.ts
+├── router.tsx
+└── env.ts
+```
 
-// routes/users/index.tsx
-import { useUserForm } from './-hooks/use-user-form'
-import { createUser } from './-functions/user-mutations'
+## Route 파일 컨벤션
 
-// ❌ 잘못된 구조
-// routes/users/index.tsx (모든 로직이 한 파일에)
-const createUser = createServerFn({ method: 'POST' })
-  .inputValidator(schema)
-  .handler(async ({ data }) => prisma.user.create({ data }))
+### Colocation Pattern
 
-const useUserForm = () => {
-  const mutation = useMutation({ mutationFn: createUser })
-  return { mutation }
-}
+Route 파일 옆에 관련 파일들을 배치할 때 `-` prefix 사용:
 
-export const Route = createFileRoute('/users')({
-  component: UsersPage,
-})
+```
+routes/
+├── posts.index.tsx
+├── posts.index-components/
+│   ├── PostCard.tsx
+│   └── PostsList.tsx
+├── posts.index-hooks/
+│   └── usePosts.ts
+├── posts.$postId.tsx
+├── posts.$postId-components/
+│   ├── PostHeader.tsx
+│   └── CommentSection.tsx
+└── posts.$postId-functions/
+    ├── updatePost.ts
+    └── deletePost.ts
 ```
 
-### 환경 변수
-
-| ✅ Do | ❌ Don't |
-|-------|----------|
-| Server Function에서만 `process.env` 사용 | loader에서 직접 사용 |
-| Zod로 환경 변수 검증 | 검증 없이 사용 |
+**규칙**: `-components`, `-hooks`, `-functions` 접미사 사용
 
-### 예시: 환경 변수
+### ✅ 올바른 패턴
 
 ```typescript
-// ✅ 올바른 패턴
-// lib/env.ts
-const envSchema = z.object({
-  DATABASE_URL: z.string().url(),
-  API_SECRET: z.string().min(32),
-})
+// posts.index-functions/getPosts.ts
+import { createServerFn } from '@tanstack/react-start'
 
-export const env = envSchema.parse(process.env)
+export const getPosts = createServerFn({ method: 'GET' }).handler(
+  async () => {
+    return db.post.findMany()
+  }
+)
 
-// functions/config.ts
-const getConfig = createServerFn({ method: 'GET' })
-  .middleware([authMiddleware])
-  .handler(async () => {
-    return {
-      secret: env.API_SECRET, // ✅ 서버에서만 실행
-    }
-  })
+// posts.index-components/PostCard.tsx
+export function PostCard({ post }: { post: Post }) {
+  return <div>{post.title}</div>
+}
 
-// ❌ 잘못된 패턴
-export const Route = createFileRoute('/config')({
-  loader: () => {
-    const secret = process.env.API_SECRET // ❌ 클라이언트에 노출됨!
-    return { secret }
+// posts.index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { getPosts } from './posts.index-functions/getPosts'
+import { PostCard } from './posts.index-components/PostCard'
+
+export const Route = createFileRoute('/posts/')({
+  loader: async () => {
+    const posts = await getPosts()
+    return { posts }
   },
+  component: PostsList,
 })
+
+function PostsList() {
+  const { posts } = Route.useLoaderData()
+  return (
+    <div>
+      {posts.map((post) => (
+        <PostCard key={post.id} post={post} />
+      ))}
+    </div>
+  )
+}
 ```
 
-</dos_donts>
+### ❌ 잘못된 패턴
+
+```
+routes/
+├── posts.index.tsx
+├── PostCard.tsx  ❌ Route 파일과 혼재
+└── getPosts.ts   ❌ 명확한 분류 없음
+```
+
+</file_structure>
 
 ---
 
-<quick_reference>
+<dos_donts>
 
-## Quick Reference
+## Do's
+
+| 패턴 | 예시 |
+|------|------|
+| **✅ .inputValidator() 사용** | `createServerFn({ method: 'POST' }).inputValidator(schema)` |
+| **✅ Middleware로 인증** | `.middleware([authMiddleware])` |
+| **✅ Helper functions 분리** | `import 'server-only'` + 별도 파일 |
+| **✅ TanStack Query로 호출** | `useSuspenseQuery`, `useMutation` |
+| **✅ beforeLoad로 guard** | `beforeLoad: async () => { if (!session) throw redirect() }` |
+| **✅ Zod로 입력 검증** | `z.email()`, `z.url()`, `z.string().min()` |
+| **✅ 명시적 return type** | `function getData(): Promise<User[]>` |
+| **✅ Server env 분리** | Server: `process.env`, Client: `import.meta.env.VITE_*` |
+| **✅ SWR caching 활용** | `staleTime`, `gcTime`, `shouldReload` 설정 |
+| **✅ Streaming SSR** | `<Suspense>` + `useSuspenseQuery` |
+
+## Don'ts
+
+| 패턴 | 이유 |
+|------|------|
+| **❌ .validator() 사용** | Deprecated. `.inputValidator()` 사용 필수 |
+| **❌ createAPIFileRoute()** | Deprecated. `createServerFileRoute().methods()` 사용 |
+| **❌ @tanstack/start** | 패키지명 변경됨. `@tanstack/react-start` 사용 |
+| **❌ Server Function에 민감 로직** | 클라이언트 번들 포함 위험. Helper 분리 |
+| **❌ Server에서 import.meta.env** | 서버에서는 `process.env` 사용 |
+| **❌ Client에서 process.env** | 클라이언트에서는 `import.meta.env.VITE_*` 사용 |
+| **❌ verbatimModuleSyntax: true** | TanStack Start 호환성 문제 |
+| **❌ gcTime: 0 남발** | 캐시 무효화. 신중히 사용 |
+| **❌ any 타입** | Type safety 상실. `unknown` 또는 명시적 타입 |
+| **❌ Route 파일에 비즈니스 로직** | 관심사 분리. `-functions/` 사용 |
+
+## 마이그레이션 체크리스트
+
+### v1.121.0+ 업데이트
+
+| 변경 전 | 변경 후 |
+|---------|---------|
+| `import { createServerFn } from '@tanstack/start'` | `import { createServerFn } from '@tanstack/react-start'` |
+| `.validator(schema)` | `.inputValidator(schema)` |
+| `createAPIFileRoute('/api/users')` | `createServerFileRoute('/api/users').methods({ GET, POST })` |
+| Vinxi config | Vite config (`vite.config.ts`) |
 
-### GET: 데이터 조회
+</dos_donts>
 
-```typescript
-export const getUsers = createServerFn({ method: 'GET' })
-  .handler(async () => prisma.user.findMany())
+---
 
-export const getMyProfile = createServerFn({ method: 'GET' })
-  .middleware([authMiddleware])
-  .handler(async ({ context }) => context.user)
-```
+<quick_reference>
 
-### POST: 데이터 생성 (inputValidator 필수)
+## Server Function 템플릿
 
 ```typescript
-const schema = z.object({
-  email: z.email(),
-  name: z.string().min(1),
-})
+// GET
+export const getData = createServerFn({ method: 'GET' })
+  .inputValidator(z.object({ id: z.string() }))
+  .handler(async ({ data }) => {
+    return await getDataFromDB(data.id)
+  })
 
-export const createUser = createServerFn({ method: 'POST' })
+// POST
+export const createData = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ name: z.string() }))
   .middleware([authMiddleware])
-  .inputValidator(schema)
   .handler(async ({ data, context }) => {
-    return prisma.user.create({
-      data: { ...data, createdBy: context.user.id },
+    return await createDataInDB({
+      ...data,
+      userId: context.user.id,
     })
   })
-```
 
-### PUT/PATCH: 데이터 수정 (inputValidator 필수)
-
-```typescript
-export const updateUser = createServerFn({ method: 'PUT' })
-  .middleware([authMiddleware])
+// PUT
+export const updateData = createServerFn({ method: 'PUT' })
   .inputValidator(z.object({ id: z.string(), name: z.string() }))
+  .middleware([authMiddleware])
   .handler(async ({ data }) => {
-    return prisma.user.update({
-      where: { id: data.id },
-      data: { name: data.name },
-    })
+    return await updateDataInDB(data.id, data)
   })
-```
-
-### DELETE: 데이터 삭제
 
-```typescript
-export const deletePost = createServerFn({ method: 'DELETE' })
-  .middleware([authMiddleware])
+// DELETE
+export const deleteData = createServerFn({ method: 'DELETE' })
   .inputValidator(z.object({ id: z.string() }))
+  .middleware([authMiddleware, adminMiddleware])
   .handler(async ({ data }) => {
-    return prisma.post.delete({ where: { id: data.id } })
+    await deleteDataFromDB(data.id)
+    return { success: true }
   })
 ```
 
-### Loader: 데이터 사전 로드
+## Route 템플릿
 
 ```typescript
-export const Route = createFileRoute('/users')({
-  component: UsersPage,
+// Basic Route
+export const Route = createFileRoute('/path')({
+  component: Component,
+})
+
+// Route with Loader
+export const Route = createFileRoute('/path')({
   loader: async () => {
-    const users = await getUsers()
-    return { users }
+    const data = await getData()
+    return { data }
   },
+  component: Component,
 })
 
-const UsersPage = (): JSX.Element => {
-  const { users } = Route.useLoaderData()
-  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>
-}
+// Route with Params
+export const Route = createFileRoute('/path/$id')({
+  loader: async ({ params }) => {
+    const data = await getData({ data: { id: params.id } })
+    return { data }
+  },
+  component: Component,
+})
+
+// Route with Search
+export const Route = createFileRoute('/path')({
+  validateSearch: z.object({
+    q: z.string().optional(),
+  }),
+  loaderDeps: ({ search }) => ({ search }),
+  loader: async ({ deps }) => {
+    const results = await search(deps.search.q)
+    return { results }
+  },
+  component: Component,
+})
+
+// Protected Route
+export const Route = createFileRoute('/_auth/path')({
+  beforeLoad: async ({ context }) => {
+    const session = await getSession()
+    if (!session) throw redirect({ to: '/login' })
+    return { user: session.user }
+  },
+  component: Component,
+})
 ```
 
-### TanStack Query: useQuery
+## Middleware 템플릿
 
 ```typescript
-const { data, isLoading, error } = useQuery({
-  queryKey: ['posts'],
-  queryFn: () => getPosts(),
-})
+// Auth Middleware
+export const authMiddleware = createMiddleware().server(
+  async ({ next }) => {
+    const session = await getSession()
+    if (!session) throw new Error('Unauthorized')
+    return next({ context: { user: session.user } })
+  }
+)
+
+// Validation Middleware
+export const validateMiddleware = <T extends z.ZodType>(schema: T) =>
+  createMiddleware().server(async ({ next, data }) => {
+    const validated = schema.parse(data)
+    return next({ context: { validated } })
+  })
+
+// Logging Middleware
+export const loggingMiddleware = createMiddleware().server(
+  async ({ next, method, url }) => {
+    console.log(`[${method}] ${url}`)
+    const result = await next()
+    console.log(`[${method}] ${url} - Success`)
+    return result
+  }
+)
 ```
 
-### TanStack Query: useMutation
+## TanStack Query 템플릿
 
 ```typescript
-const queryClient = useQueryClient()
+// useSuspenseQuery (GET)
+const { data } = useSuspenseQuery({
+  queryKey: ['key', id],
+  queryFn: () => getData({ data: { id } }),
+})
 
+// useMutation (POST/PUT/DELETE)
 const mutation = useMutation({
-  mutationFn: createPost,
-  onSuccess: () => {
-    queryClient.invalidateQueries({ queryKey: ['posts'] })
+  mutationFn: createData,
+  onSuccess: (data) => {
+    queryClient.invalidateQueries({ queryKey: ['key'] })
   },
 })
 
-mutation.mutate({ title: 'New Post', content: 'Content' })
+mutation.mutate({ data: { name: 'value' } })
 ```
 
-### 인증 미들웨어
+## Server Routes 템플릿
 
 ```typescript
-const authMiddleware = createMiddleware({ type: 'function' })
-  .server(async ({ next }) => {
-    const session = await getSession()
-    if (!session) throw redirect({ to: '/login' })
-    return next({ context: { user: session.user } })
+// RESTful API
+export const Route = createServerFileRoute('/api/resource/$id')
+  .methods({
+    GET: async ({ params }) => {
+      const data = await getResource(params.id)
+      return Response.json(data)
+    },
+    PUT: async ({ request, params }) => {
+      const body = await request.json()
+      const data = await updateResource(params.id, body)
+      return Response.json(data)
+    },
+    DELETE: async ({ params }) => {
+      await deleteResource(params.id)
+      return Response.json({ success: true })
+    },
   })
 ```
 
-### 보호된 라우트
+## Auth 템플릿
 
 ```typescript
-export const Route = createFileRoute('/dashboard')({
-  beforeLoad: async () => {
-    const user = await getCurrentUser()
-    if (!user) throw redirect({ to: '/login' })
-    return { user }
+// Auth Server Functions
+export const signIn = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ email: z.email(), password: z.string() }))
+  .handler(async ({ data }) => {
+    return await auth.api.signInEmail(data)
+  })
+
+export const getSession = createServerFn({ method: 'GET' })
+  .handler(async () => {
+    return await auth.api.getSession()
+  })
+
+// Protected Route
+export const Route = createFileRoute('/_auth')({
+  beforeLoad: async ({ location }) => {
+    const session = await getSession()
+    if (!session) {
+      throw redirect({ to: '/login', search: { redirect: location.href } })
+    }
+    return { user: session.user }
   },
-  component: DashboardPage,
 })
 ```
 
+## Deployment 템플릿
+
+### Cloudflare Workers
+
+```typescript
+// app/entry.server.tsx
+export default {
+  async fetch(request: Request, env: Env) {
+    return handleRequest(request, { env })
+  },
+}
+```
+
+### Vercel
+
+```json
+// vercel.json
+{
+  "buildCommand": "npm run build",
+  "framework": "vite"
+}
+```
+
+### Netlify
+
+```toml
+# netlify.toml
+[build]
+  command = "npm run build"
+  publish = "dist/public"
+
+[[redirects]]
+  from = "/*"
+  to = "/.netlify/functions/server"
+  status = 200
+```
+
 </quick_reference>
 
 ---
 
 <version_info>
 
-**Version:** v1.x
+## 버전 정보
+
+**현재 버전**: v1.x (RC, ~v1.159.x)
+
+**주요 변경사항**:
+
+| 버전 | 변경 내용 |
+|------|-----------|
+| v1.121.0+ | `@tanstack/start` → `@tanstack/react-start` 패키지명 변경 |
+| v1.x | Vinxi → Vite 빌드 시스템 마이그레이션 |
+| v1.x | `.validator()` → `.inputValidator()` (deprecated) |
+| v1.x | `createAPIFileRoute()` → `createServerFileRoute().methods()` |
+| v1.x | React 18+ or 19+ 지원 |
+| v1.x | Vite 7+ 필수 |
+| v1.x | Node.js >=22.12.0 필수 |
+
+**Breaking Changes**:
+
+1. **패키지명 변경**: `@tanstack/start` → `@tanstack/react-start`
+2. **빌드 시스템**: Vinxi config → Vite config
+3. **Validator API**: `.validator()` deprecated, `.inputValidator()` 사용
+4. **Server Routes API**: `createAPIFileRoute()` deprecated, `createServerFileRoute().methods()` 사용
+
+**마이그레이션 가이드**:
+
+```bash
+# 1. 패키지 업데이트
+npm uninstall @tanstack/start
+npm install @tanstack/react-start@latest
+
+# 2. Import 변경
+# Before: import { createServerFn } from '@tanstack/start'
+# After:  import { createServerFn } from '@tanstack/react-start'
+
+# 3. Validator 변경
+# Before: .validator(schema)
+# After:  .inputValidator(schema)
+
+# 4. Server Routes 변경
+# Before: createAPIFileRoute('/api/users')
+# After:  createServerFileRoute('/api/users').methods({ GET, POST })
+
+# 5. Vite config 생성
+# vinxi.config.ts 삭제 → vite.config.ts 생성
+```
+
+**향후 계획**:
+
+- **React Server Components**: v1.x에 non-breaking 방식으로 추가 예정
+- **Static Server Functions**: Experimental 단계, 정식 지원 예정
+- **v2.0**: Breaking changes 예정 (정확한 일정 미정)
+
+**호환성**:
+
+| 패키지 | 최소 버전 | 권장 버전 |
+|--------|-----------|-----------|
+| React | 18.0.0 | 19.x |
+| Vite | 7.0.0 | 7.x |
+| Node.js | 22.12.0 | 22.x LTS |
+| TypeScript | 5.0.0 | 5.x |
+
+**알려진 이슈**:
+
+- `verbatimModuleSyntax: true` 사용 시 호환성 문제
+- Full `strict` mode 대신 `strictNullChecks: true` 권장
+
+**참고 자료**:
 
-**Key Changes in v1:**
-- `.inputValidator()` (v1) replaces `.validator()` (deprecated)
-- Enhanced middleware system with context passing
-- Improved type safety for Server Functions
-- Better TanStack Query integration
+- Official Docs: https://tanstack.com/start
+- GitHub: https://github.com/TanStack/router
+- Discord: https://tanstack.com/discord
 
 </version_info>