@kood/claude-code 0.1.6 → 0.1.9

package/templates/tanstack-start/docs/guides/getting-started.md

@@ -1,29 +1,21 @@
 # Getting Started
 
-TanStack Start 프로젝트 시작 가이드입니다.
+TanStack Start 프로젝트 시작 가이드.
 
 ## Prerequisites
 
 - Node.js 18+
 - Yarn
-- Claude Code CLI
 
-## Project Setup
-
-### 1. Create TanStack Start Project
+## 프로젝트 생성
 
 ```bash
 npx create-tsrouter-app@latest my-app --template start
 cd my-app
-```
-
-### 2. Install Dependencies
-
-```bash
 yarn install
 ```
 
-### 3. Add Essential Packages
+## 필수 패키지 설치
 
 ```bash
 # Database (Prisma 7.x)
@@ -35,85 +27,9 @@ yarn add zod
 
 # TanStack Query
 yarn add @tanstack/react-query
-
-# UI (optional)
-yarn add tailwindcss postcss autoprefixer
-npx tailwindcss init -p
-```
-
-### 4. Initialize Prisma
-
-```bash
-npx prisma init
-```
-
-## Project Structure
-
-```
-my-app/
-├── src/
-│   ├── routes/
-│   │   ├── __root.tsx
-│   │   ├── index.tsx
-│   │   └── users/
-│   │       ├── index.tsx
-│   │       ├── route.tsx           # 필요시 route 설정
-│   │       ├── -components/        # 페이지 전용 컴포넌트
-│   │       │   └── user-card.tsx
-│   │       ├── -sections/          # 섹션 분리 (복잡한 경우)
-│   │       │   ├── user-list-section.tsx
-│   │       │   └── user-filter-section.tsx
-│   │       └── -hooks/             # 페이지 전용 훅
-│   │           ├── use-users.ts
-│   │           └── use-user-filter.ts
-│   ├── components/                 # 공통 컴포넌트
-│   │   └── ui/
-│   │       ├── button.tsx
-│   │       └── input.tsx
-│   ├── database/                   # 데이터베이스 관련
-│   │   └── prisma.ts               # Prisma Client 인스턴스
-│   ├── services/                   # 도메인별 SDK/서비스 레이어
-│   │   ├── user/
-│   │   │   ├── index.ts            # 진입점 (re-export)
-│   │   │   ├── schemas.ts          # Zod 스키마
-│   │   │   ├── queries.ts          # GET 요청
-│   │   │   └── mutations.ts        # POST 요청
-│   │   └── auth/
-│   │       ├── index.ts
-│   │       ├── schemas.ts
-│   │       ├── queries.ts
-│   │       └── mutations.ts
-│   ├── lib/                        # 공통 유틸리티
-│   │   ├── query-client.ts
-│   │   └── utils.ts
-│   └── styles/
-│       └── app.css
-├── generated/
-│   └── prisma/                     # Prisma Client 출력
-├── prisma/
-│   └── schema.prisma
-├── app.config.ts
-├── package.json
-└── tsconfig.json
-```
-
-## Route Folder Convention
-
-TanStack Start에서 `-` 접두사는 라우트에서 제외됩니다:
-
-```
-routes/users/
-├── index.tsx              # /users 페이지
-├── route.tsx              # route 설정 (loader, beforeLoad 등)
-├── -components/           # ❌ 라우트 아님, 컴포넌트 폴더
-│   └── user-card.tsx
-├── -sections/             # ❌ 라우트 아님, 섹션 폴더
-│   └── user-list-section.tsx
-└── -hooks/                # ❌ 라우트 아님, 훅 폴더
-    └── use-users.ts
 ```
 
-## Core Configuration
+## 초기 설정
 
 ### app.config.ts
 
@@ -132,7 +48,6 @@ export default defineConfig({
 ```tsx
 // src/routes/__root.tsx
 import { createRootRoute, Outlet } from '@tanstack/react-router'
-import { TanStackRouterDevtools } from '@tanstack/router-devtools'
 
 export const Route = createRootRoute({
   component: RootComponent,
@@ -140,17 +55,14 @@ export const Route = createRootRoute({
 
 const RootComponent = (): JSX.Element => {
   return (
-    <>
-      <div className="min-h-screen">
-        <nav className="border-b p-4">
-          <a href="/" className="font-bold">My App</a>
-        </nav>
-        <main className="container mx-auto p-4">
-          <Outlet />
-        </main>
-      </div>
-      <TanStackRouterDevtools />
-    </>
+    <div className="min-h-screen">
+      <nav className="border-b p-4">
+        <a href="/" className="font-bold">My App</a>
+      </nav>
+      <main className="container mx-auto p-4">
+        <Outlet />
+      </main>
+    </div>
   )
 }
 ```
@@ -174,29 +86,6 @@ const HomePage = (): JSX.Element => {
 }
 ```
 
-## Services Setup
-
-### Database Setup
-
-```typescript
-// src/database/prisma.ts
-import { PrismaClient } from '../../generated/prisma'
-
-const globalForPrisma = globalThis as unknown as {
-  prisma: PrismaClient | undefined
-}
-
-export const prisma =
-  globalForPrisma.prisma ??
-  new PrismaClient({
-    log: process.env.NODE_ENV === 'development' ? ['query'] : [],
-  })
-
-if (process.env.NODE_ENV !== 'production') {
-  globalForPrisma.prisma = prisma
-}
-```
-
 ### Query Client
 
 ```typescript
@@ -206,99 +95,23 @@ import { QueryClient } from '@tanstack/react-query'
 export const createQueryClient = (): QueryClient => {
   return new QueryClient({
     defaultOptions: {
-      queries: {
-        staleTime: 60 * 1000,
-        retry: 1,
-      },
+      queries: { staleTime: 60 * 1000, retry: 1 },
     },
   })
 }
 ```
 
-### User Service (도메인 폴더 구조)
-
-```typescript
-// src/services/user/schemas.ts
-import { z } from 'zod'
-
-export const createUserSchema = z.object({
-  email: z.email(),
-  name: z.string().min(1).max(100).trim(),
-})
-
-export const updateUserSchema = z.object({
-  id: z.string(),
-  email: z.email().optional(),
-  name: z.string().min(1).max(100).trim().optional(),
-})
-
-export type CreateUserInput = z.infer<typeof createUserSchema>
-export type UpdateUserInput = z.infer<typeof updateUserSchema>
-```
-
-```typescript
-// src/services/user/queries.ts
-import { createServerFn } from '@tanstack/react-start'
-import { prisma } from '@/database/prisma'
-
-export const getUsers = createServerFn({ method: 'GET' })
-  .handler(async () => {
-    return prisma.user.findMany({
-      orderBy: { createdAt: 'desc' },
-    })
-  })
-
-export const getUserById = createServerFn({ method: 'GET' })
-  .handler(async ({ data: id }: { data: string }) => {
-    const user = await prisma.user.findUnique({ where: { id } })
-    if (!user) throw new Error('User not found')
-    return user
-  })
-```
-
-```typescript
-// src/services/user/mutations.ts
-import { createServerFn } from '@tanstack/react-start'
-import { prisma } from '@/database/prisma'
-import { createUserSchema, updateUserSchema } from './schemas'
-
-export const createUser = createServerFn({ method: 'POST' })
-  .inputValidator(createUserSchema)
-  .handler(async ({ data }) => {
-    return prisma.user.create({ data })
-  })
-
-export const updateUser = createServerFn({ method: 'POST' })
-  .inputValidator(updateUserSchema)
-  .handler(async ({ data }) => {
-    const { id, ...updateData } = data
-    return prisma.user.update({ where: { id }, data: updateData })
-  })
-
-export const deleteUser = createServerFn({ method: 'POST' })
-  .handler(async ({ data: id }: { data: string }) => {
-    return prisma.user.delete({ where: { id } })
-  })
-```
-
-```typescript
-// src/services/user/index.ts
-export * from './schemas'
-export * from './queries'
-export * from './mutations'
-```
-
-## Development Commands
+## 개발 명령어
 
 | Command | Description |
 |---------|-------------|
-| `yarn dev` | Start development server |
-| `yarn build` | Build for production |
-| `yarn start` | Start production server |
-| `yarn test` | Run tests |
-| `yarn lint` | Check code quality |
+| `yarn dev` | 개발 서버 시작 |
+| `yarn build` | 프로덕션 빌드 |
+| `yarn start` | 프로덕션 서버 |
 
-## Next Steps
+## 다음 단계
 
-- [Best Practices](./best-practices.md) - 개발 모범 사례
-- [Project Templates](./project-templates.md) - 프로젝트 템플릿
+- [conventions.md](./conventions.md) - 코드 컨벤션
+- [routes.md](./routes.md) - 라우트 구조
+- [hooks.md](./hooks.md) - Custom Hook 패턴
+- [services.md](./services.md) - Service Layer

package/templates/tanstack-start/docs/guides/hooks.md

@@ -0,0 +1,166 @@
+# Custom Hook 패턴
+
+페이지/섹션의 모든 로직, 상태, 라이프사이클을 중앙화.
+
+## 필수: Hook 내부 순서
+
+```
+1. State (useState, zustand store)
+2. Global Hooks (useParams, useNavigate, useQueryClient)
+3. React Query (useQuery → useMutation)
+4. Event Handlers & Functions
+5. useMemo
+6. useEffect
+```
+
+## Page Hook 예시
+
+```typescript
+// routes/users/-hooks/use-users.ts
+import { useState, useMemo, useEffect, useCallback } from 'react'
+import { useParams, useNavigate } from '@tanstack/react-router'
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { useAuthStore } from '@/stores/auth'
+import { getUsers, createUser, deleteUser } from '@/services/user'
+import type { User } from '@/types'
+
+interface UseUsersReturn {
+  users: User[] | undefined
+  filteredUsers: User[]
+  isLoading: boolean
+  error: Error | null
+  search: string
+  setSearch: (value: string) => void
+  handleCreate: (data: { email: string; name: string }) => void
+  handleDelete: (id: string) => void
+  isCreating: boolean
+  isDeleting: boolean
+}
+
+export const useUsers = (): UseUsersReturn => {
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 1. State
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const [search, setSearch] = useState('')
+  const { user: currentUser } = useAuthStore()
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 2. Global Hooks
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const params = useParams({ from: '/users/$id' })
+  const navigate = useNavigate()
+  const queryClient = useQueryClient()
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 3. React Query
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const { data: users, isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => getUsers(),
+  })
+
+  const createMutation = useMutation({
+    mutationFn: createUser,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+  })
+
+  const deleteMutation = useMutation({
+    mutationFn: deleteUser,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+  })
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 4. Event Handlers
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const handleCreate = useCallback(
+    (data: { email: string; name: string }) => {
+      createMutation.mutate({ data })
+    },
+    [createMutation]
+  )
+
+  const handleDelete = useCallback(
+    (id: string) => {
+      deleteMutation.mutate({ data: id })
+    },
+    [deleteMutation]
+  )
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 5. useMemo
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const filteredUsers = useMemo(() => {
+    if (!users) return []
+    if (!search) return users
+    return users.filter((user) =>
+      user.name.toLowerCase().includes(search.toLowerCase())
+    )
+  }, [users, search])
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 6. useEffect
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  useEffect(() => {
+    if (!currentUser) {
+      navigate({ to: '/login' })
+    }
+  }, [currentUser, navigate])
+
+  return {
+    users,
+    filteredUsers,
+    isLoading,
+    error,
+    search,
+    setSearch,
+    handleCreate,
+    handleDelete,
+    isCreating: createMutation.isPending,
+    isDeleting: deleteMutation.isPending,
+  }
+}
+```
+
+## 잘못된 순서 (금지)
+
+```typescript
+// ❌ 순서가 뒤섞인 잘못된 예시
+export const useBadHook = () => {
+  const queryClient = useQueryClient()  // ❌ Global Hook이 먼저
+
+  useEffect(() => { /* ... */ }, [])    // ❌ useEffect가 중간에
+
+  const [state, setState] = useState()  // ❌ State가 나중에
+
+  const { data } = useQuery({ /* ... */ })  // ❌ Query가 Effect 다음에
+
+  const computed = useMemo(() => {}, [])  // ❌ useMemo 위치 잘못됨
+}
+```
+
+## Filter Hook 예시
+
+```typescript
+// routes/users/-hooks/use-user-filter.ts
+import { useState, useCallback } from 'react'
+
+interface UseUserFilterReturn {
+  search: string
+  setSearch: (value: string) => void
+  role: string
+  setRole: (value: string) => void
+  clearFilters: () => void
+}
+
+export const useUserFilter = (): UseUserFilterReturn => {
+  const [search, setSearch] = useState('')
+  const [role, setRole] = useState('')
+
+  const clearFilters = useCallback(() => {
+    setSearch('')
+    setRole('')
+  }, [])
+
+  return { search, setSearch, role, setRole, clearFilters }
+}
+```

package/templates/tanstack-start/docs/guides/routes.md

@@ -0,0 +1,166 @@
+# 라우트 구조
+
+TanStack Start 파일 기반 라우팅 패턴.
+
+## Route 폴더 구조
+
+```
+routes/<route-name>/
+├── index.tsx              # 페이지 컴포넌트
+├── route.tsx              # route 설정 (필요시)
+├── -components/           # 페이지 전용 컴포넌트
+│   ├── user-card.tsx
+│   └── user-form.tsx
+├── -sections/             # 섹션 분리 (복잡한 경우)
+│   ├── user-list-section.tsx
+│   └── user-filter-section.tsx
+└── -hooks/                # 페이지 전용 훅
+    ├── use-users.ts
+    └── use-user-filter.ts
+```
+
+## `-` 접두사
+
+`-` 접두사가 있는 폴더는 라우트에서 제외:
+
+```
+routes/users/
+├── index.tsx          # /users ✅ 라우트
+├── $id.tsx            # /users/:id ✅ 라우트
+├── -components/       # ❌ 라우트 아님
+├── -sections/         # ❌ 라우트 아님
+└── -hooks/            # ❌ 라우트 아님
+```
+
+## 기본 Route 패턴
+
+```tsx
+// routes/users/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { UserListSection } from './-sections/user-list-section'
+import { UserFilterSection } from './-sections/user-filter-section'
+
+export const Route = createFileRoute('/users/')({
+  component: UsersPage,
+})
+
+const UsersPage = (): JSX.Element => {
+  return (
+    <div className="container mx-auto p-4">
+      <h1 className="text-2xl font-bold mb-4">Users</h1>
+      <UserFilterSection />
+      <UserListSection />
+    </div>
+  )
+}
+```
+
+## Section 패턴
+
+```tsx
+// routes/users/-sections/user-list-section.tsx
+import { useUsers } from '../-hooks/use-users'
+import { UserCard } from '../-components/user-card'
+
+export const UserListSection = (): JSX.Element => {
+  const { users, isLoading, error, deleteUser, isDeleting } = useUsers()
+
+  if (isLoading) return <div className="text-center py-8">Loading...</div>
+  if (error) return <div className="text-red-600 py-8">Error: {error.message}</div>
+  if (!users?.length) return <div className="text-gray-500 py-8">No users found</div>
+
+  return (
+    <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
+      {users.map((user) => (
+        <UserCard
+          key={user.id}
+          user={user}
+          onDelete={deleteUser}
+          isDeleting={isDeleting}
+        />
+      ))}
+    </div>
+  )
+}
+```
+
+## Filter Section 패턴
+
+```tsx
+// routes/users/-sections/user-filter-section.tsx
+import { useUserFilter } from '../-hooks/use-user-filter'
+import { Input } from '@/components/ui/input'
+import { Button } from '@/components/ui/button'
+
+export const UserFilterSection = (): JSX.Element => {
+  const { search, setSearch, role, setRole, clearFilters } = useUserFilter()
+
+  return (
+    <div className="flex gap-4 mb-6">
+      <Input
+        placeholder="Search users..."
+        value={search}
+        onChange={(e) => setSearch(e.target.value)}
+        className="max-w-xs"
+      />
+      <select
+        value={role}
+        onChange={(e) => setRole(e.target.value)}
+        className="border rounded px-3 py-2"
+      >
+        <option value="">All Roles</option>
+        <option value="USER">User</option>
+        <option value="ADMIN">Admin</option>
+      </select>
+      <Button variant="outline" onClick={clearFilters}>
+        Clear
+      </Button>
+    </div>
+  )
+}
+```
+
+## 컴포넌트 패턴
+
+```tsx
+// routes/users/-components/user-card.tsx
+import type { User } from '@/types'
+import { Button } from '@/components/ui/button'
+
+interface UserCardProps {
+  user: User
+  onDelete?: (id: string) => void
+  isDeleting?: boolean
+}
+
+export const UserCard = ({
+  user,
+  onDelete,
+  isDeleting,
+}: UserCardProps): JSX.Element => {
+  return (
+    <div className="rounded-lg border p-4 shadow-sm">
+      <div className="flex items-center gap-4">
+        <div className="h-12 w-12 rounded-full bg-gray-200" />
+        <div>
+          <h3 className="font-semibold">{user.name}</h3>
+          <p className="text-sm text-gray-600">{user.email}</p>
+        </div>
+      </div>
+
+      {onDelete && (
+        <div className="mt-4">
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => onDelete(user.id)}
+            disabled={isDeleting}
+          >
+            {isDeleting ? 'Deleting...' : 'Delete'}
+          </Button>
+        </div>
+      )}
+    </div>
+  )
+}
+```