@kood/claude-code 0.1.0

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

@@ -0,0 +1,163 @@
+# 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'
+
+export const Route = createFileRoute('/')({
+  component: Page,
+  loader: async () => {
+    const res = await fetch('https://api.example.com/posts')
+    return res.json()
+  },
+})
+
+function Page() {
+  const posts = Route.useLoaderData()
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>{post.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('서버에서 초기 요청 시 실행')
+  },
+  component: () => <div>서버에서 렌더링됨</div>,
+})
+```
+
+### SSR 옵션
+
+```typescript
+// 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!')
+      },
+      POST: async ({ request }) => {
+        const body = await request.json()
+        return new Response(`Hello, ${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>
+}
+```

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

@@ -0,0 +1,128 @@
+# TanStack Start - Server Functions
+
+> **상위 문서**: [TanStack Start](./index.md)
+
+Server Functions는 서버에서만 실행되는 타입 안전한 함수입니다.
+
+## 기본 Server Function
+
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+
+// 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'
+
+const createUserSchema = z.object({
+  email: z.string().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 })
+  })
+```
+
+## 컴포넌트에서 호출
+
+### useServerFn 사용
+
+```tsx
+import { useServerFn } from '@tanstack/react-start'
+import { useQuery } from '@tanstack/react-query'
+import { getServerPosts } from '~/lib/server-functions'
+
+function PostList() {
+  const getPosts = useServerFn(getServerPosts)
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['posts'],
+    queryFn: () => getPosts(),
+  })
+
+  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>
+  )
+}
+```
+
+## 보안 패턴
+
+### 서버 전용 데이터 보호
+
+```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}`)
+})
+
+export const Route = createFileRoute('/users')({
+  loader: () => getUsersSecurely(),
+})
+```

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

@@ -0,0 +1,85 @@
+# TanStack Start - 설치 및 설정
+
+> **상위 문서**: [TanStack Start](./index.md)
+
+## 패키지 설치
+
+```bash
+yarn add @tanstack/react-start @tanstack/react-router vinxi
+yarn add -D vite @vitejs/plugin-react vite-tsconfig-paths
+```
+
+## Vite 설정
+
+```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'
+
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+  plugins: [
+    tsConfigPaths(),
+    tanstackStart(),
+    viteReact(),
+  ],
+})
+```
+
+## TypeScript 설정
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*"]
+}
+```
+
+## 프로젝트 구조
+
+```
+project/
+├── src/
+│   ├── routes/
+│   │   ├── __root.tsx
+│   │   ├── index.tsx
+│   │   └── about.tsx
+│   ├── lib/
+│   │   └── server-functions.ts
+│   └── start.ts
+├── vite.config.ts
+├── tsconfig.json
+└── package.json
+```
+
+## 환경 변수 검증
+
+```typescript
+// lib/env.ts
+import { z } from 'zod'
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  DATABASE_URL: z.string().url(),
+  API_SECRET: z.string().min(32),
+})
+
+export const env = envSchema.parse(process.env)
+```

package/templates/tanstack-start/docs/library/zod/basic-types.md

@@ -0,0 +1,186 @@
+# Zod - 기본 타입
+
+> **상위 문서**: [Zod](./index.md)
+
+## 문자열
+
+```typescript
+z.string()
+z.string().min(1)          // 최소 길이
+z.string().max(100)        // 최대 길이
+z.string().length(5)       // 정확한 길이
+z.string().regex(/^\d+$/)  // 정규식
+z.string().trim()          // 공백 제거
+z.string().toLowerCase()   // 소문자 변환
+z.string().toUpperCase()   // 대문자 변환
+```
+
+### v4 새로운 최상위 문자열 포맷 API
+
+```typescript
+// 더 나은 tree-shaking을 위해 최상위 API 사용 권장
+z.email()           // 이메일 형식
+z.url()             // URL 형식
+z.uuid()            // UUID 형식
+z.base64()          // Base64 형식
+z.base64url()       // Base64 URL 형식
+z.nanoid()          // NanoID 형식
+z.cuid()            // CUID 형식
+z.cuid2()           // CUID2 형식
+z.ulid()            // ULID 형식
+z.emoji()           // 이모지 (단일 문자)
+z.ipv4()            // IPv4 주소
+z.ipv6()            // IPv6 주소
+z.cidrv4()          // IPv4 범위
+z.cidrv6()          // IPv6 범위
+
+// ISO 날짜/시간 형식
+z.iso.date()        // ISO 날짜 (2024-01-15)
+z.iso.time()        // ISO 시간 (14:30:00)
+z.iso.datetime()    // ISO 날짜시간
+z.iso.duration()    // ISO 기간 (P1D, PT1H)
+```
+
+### 템플릿 리터럴 타입 (v4 신규)
+
+```typescript
+const hello = z.templateLiteral(["hello, ", z.string()])
+// `hello, ${string}`
+
+const cssUnits = z.enum(["px", "em", "rem", "%"])
+const css = z.templateLiteral([z.number(), cssUnits])
+// `${number}px` | `${number}em` | `${number}rem` | `${number}%`
+
+const email = z.templateLiteral([
+  z.string().min(1),
+  "@",
+  z.string().max(64),
+])
+// `${string}@${string}` (min/max refinements도 적용됨!)
+```
+
+## 숫자
+
+```typescript
+z.number()
+z.number().min(0)          // 최솟값
+z.number().max(100)        // 최댓값
+z.number().int()           // 정수만
+z.number().positive()      // 양수만
+z.number().negative()      // 음수만
+z.number().nonnegative()   // 0 이상
+z.number().nonpositive()   // 0 이하
+z.number().finite()        // 유한 숫자
+z.number().safe()          // 안전한 정수 범위
+```
+
+## 불리언
+
+```typescript
+z.boolean()
+```
+
+### 문자열 불리언 (v4 신규)
+
+환경변수 스타일 불리언 변환:
+
+```typescript
+const strbool = z.stringbool()
+
+strbool.parse("true")     // => true
+strbool.parse("1")        // => true
+strbool.parse("yes")      // => true
+strbool.parse("on")       // => true
+strbool.parse("enabled")  // => true
+
+strbool.parse("false")    // => false
+strbool.parse("0")        // => false
+strbool.parse("no")       // => false
+strbool.parse("off")      // => false
+strbool.parse("disabled") // => false
+
+// 커스텀 truthy/falsy 값
+z.stringbool({
+  truthy: ["yes", "true"],
+  falsy: ["no", "false"]
+})
+```
+
+## 날짜
+
+```typescript
+z.date()
+z.date().min(new Date('2020-01-01'))
+z.date().max(new Date('2030-12-31'))
+```
+
+## BigInt
+
+```typescript
+z.bigint()
+z.bigint().positive()
+z.bigint().negative()
+```
+
+## 리터럴
+
+```typescript
+z.literal('hello')       // 정확히 'hello'만
+z.literal(42)            // 정확히 42만
+z.literal(true)          // 정확히 true만
+```
+
+## Null, Undefined, Void
+
+```typescript
+z.null()       // null만 허용
+z.undefined()  // undefined만 허용
+z.void()       // undefined 허용 (반환 타입용)
+```
+
+## Any, Unknown, Never
+
+```typescript
+z.any()      // 모든 타입 허용
+z.unknown()  // unknown 타입
+z.never()    // 값 없음 (유니온에서 사용)
+```
+
+> **v4 변경**: `z.any()`와 `z.unknown()`은 더 이상 객체에서 선택적 키로 추론되지 않습니다.
+> ```typescript
+> const mySchema = z.object({ a: z.any(), b: z.unknown() })
+> // v3: { a?: any; b?: unknown }
+> // v4: { a: any; b: unknown }
+> ```
+
+## Optional & Nullable
+
+```typescript
+z.string().optional()  // string | undefined
+z.string().nullable()  // string | null
+z.string().nullish()   // string | null | undefined
+```
+
+## Default 값
+
+```typescript
+const Schema = z.object({
+  name: z.string().default('Anonymous'),
+  role: z.enum(['admin', 'user']).default('user'),
+})
+
+Schema.parse({}) // { name: 'Anonymous', role: 'user' }
+```
+
+## 타입 추론
+
+```typescript
+const stringSchema = z.string()
+type StringType = z.infer<typeof stringSchema> // string
+
+const numberSchema = z.number().optional()
+type NumberType = z.infer<typeof numberSchema> // number | undefined
+
+const dateSchema = z.date().nullable()
+type DateType = z.infer<typeof dateSchema> // Date | null
+```