@kood/claude-code 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kood/claude-code",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Claude Code documentation installer for projects",
   "type": "module",
   "bin": "./dist/index.js",

package/templates/tanstack-start/CLAUDE.md

@@ -277,21 +277,19 @@ export const Route = createFileRoute('/users')({
 ### TanStack Query (서버 연동 시 필수)
 ```tsx
 // ✅ 데이터 조회: useQuery 필수
-const getPosts = useServerFn(getServerPosts)
 const { data } = useQuery({
-  queryKey: ['users'],
-  queryFn: () => getPosts(),
+  queryKey: ['posts'],
+  queryFn: () => getServerPosts(),
 })
 
 // ✅ 데이터 변경: useMutation 필수
-const createPostFn = useServerFn(createPost)
 const mutation = useMutation({
-  mutationFn: createPostFn,
-  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+  mutationFn: createPost,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
 })
 
-// ❌ 금지: Server Function 직접 호출
-// useEffect(() => { getPosts().then(setData) }, [])
+// ❌ 금지: Server Function을 TanStack Query 없이 직접 호출
+// useEffect(() => { getServerPosts().then(setData) }, [])
 ```
 
 ---

package/templates/tanstack-start/docs/guides/best-practices.md

@@ -304,7 +304,6 @@ const UsersPage = (): JSX.Element => {
 import { useState, useMemo, useEffect, useCallback } from 'react'
 import { useParams, useNavigate } from '@tanstack/react-router'
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { useServerFn } from '@tanstack/react-start'
 import { useAuthStore } from '@/stores/auth'
 import { getUsers, createUser, deleteUser } from '@/services/user'
 import type { User } from '@/types'
@@ -339,24 +338,20 @@ export const useUsers = (): UseUsersReturn => {
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   // 3. React Query (useQuery → useMutation)
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  const getUsersFn = useServerFn(getUsers)
-  const createUserFn = useServerFn(createUser)
-  const deleteUserFn = useServerFn(deleteUser)
-
   const { data: users, isLoading, error } = useQuery({
     queryKey: ['users'],
-    queryFn: () => getUsersFn(),
+    queryFn: () => getUsers(),
   })
 
   const createMutation = useMutation({
-    mutationFn: createUserFn,
+    mutationFn: createUser,
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['users'] })
     },
   })
 
   const deleteMutation = useMutation({
-    mutationFn: deleteUserFn,
+    mutationFn: deleteUser,
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['users'] })
     },

package/templates/tanstack-start/docs/guides/env-setup.md

@@ -226,7 +226,7 @@ export const clientEnv = parseClientEnv()
 ```typescript
 // app/server-functions/users.ts
 import { createServerFn } from '@tanstack/react-start'
-import { getServerEnv } from '~/config/env'
+import { getServerEnv } from '@/config/env'
 
 export const getUsers = createServerFn({ method: 'GET' })
   .handler(async () => {
@@ -248,7 +248,7 @@ export const getUsers = createServerFn({ method: 'GET' })
 
 ```tsx
 // app/components/AppHeader.tsx
-import { clientEnv } from '~/config/env'
+import { clientEnv } from '@/config/env'
 
 export const AppHeader = () => {
   return (
@@ -282,7 +282,7 @@ const appName = import.meta.env.VITE_APP_NAME  // ✅ VITE_ 접두사만
 
 ```typescript
 // app/lib/auth.ts
-import { getServerEnv } from '~/config/env'
+import { getServerEnv } from '@/config/env'
 
 export const getAuthConfig = () => {
   const env = getServerEnv()

package/templates/tanstack-start/docs/library/better-auth/2fa.md

@@ -103,7 +103,7 @@ await authClient.twoFactor.disable({
 ```tsx
 // pages/two-factor.tsx
 import { useState } from 'react'
-import { authClient } from '~/lib/auth-client'
+import { authClient } from '@/lib/auth-client'
 
 export default function TwoFactorPage() {
   const [code, setCode] = useState('')

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

@@ -111,7 +111,7 @@ export const auth = betterAuth({
 
 // Server Function에서 사용
 import { createServerFn } from '@tanstack/react-start'
-import { auth } from '~/lib/auth'
+import { auth } from '@/lib/auth'
 
 export const getSession = createServerFn({ method: 'GET' })
   .handler(async ({ request }) => {

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

@@ -113,7 +113,7 @@ if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma
 
 // Server Function에서 사용
 import { createServerFn } from '@tanstack/react-start'
-import { prisma } from '~/lib/prisma'
+import { prisma } from '@/lib/prisma'
 
 export const getUsers = createServerFn({ method: 'GET' })
   .handler(async () => {

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

@@ -52,15 +52,12 @@ const queryClient = new QueryClient({
 
 ```tsx
 import { useQuery } from '@tanstack/react-query'
-import { useServerFn } from '@tanstack/react-start'
-import { getServerPosts } from '~/lib/server-functions'
+import { getServerPosts } from '@/lib/server-functions'
 
 function PostList() {
-  const getPosts = useServerFn(getServerPosts)
-
   const { data, isLoading, error } = useQuery({
     queryKey: ['posts'],
-    queryFn: () => getPosts(),
+    queryFn: () => getServerPosts(),
   })
 
   if (isLoading) return <div>Loading...</div>

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

@@ -159,7 +159,7 @@ export const auth = betterAuth({
 
 // Server Function에서 사용
 import { createServerFn } from '@tanstack/react-start'
-import { auth } from '~/lib/auth'
+import { auth } from '@/lib/auth'
 
 export const getSession = createServerFn({ method: 'GET' })
   .handler(async ({ request }) => {

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

@@ -93,16 +93,13 @@ export const submitForm = createServerFn({ method: 'POST' })
 ### ✅ 올바른 패턴: useQuery 사용 (데이터 조회)
 
 ```tsx
-import { useServerFn } from '@tanstack/react-start'
 import { useQuery } from '@tanstack/react-query'
-import { getServerPosts } from '~/lib/server-functions'
+import { getServerPosts } from '@/lib/server-functions'
 
 function PostList() {
-  const getPosts = useServerFn(getServerPosts)
-
   const { data, isLoading, error } = useQuery({
     queryKey: ['posts'],
-    queryFn: () => getPosts(),
+    queryFn: () => getServerPosts(),
   })
 
   if (isLoading) return <div>Loading...</div>
@@ -121,16 +118,14 @@ function PostList() {
 ### ✅ 올바른 패턴: useMutation 사용 (데이터 변경)
 
 ```tsx
-import { useServerFn } from '@tanstack/react-start'
 import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { createPost, deletePost } from '~/lib/server-functions'
+import { createPost, deletePost } from '@/lib/server-functions'
 
 function PostForm() {
   const queryClient = useQueryClient()
-  const createPostFn = useServerFn(createPost)
 
   const mutation = useMutation({
-    mutationFn: (data: { title: string; content: string }) => createPostFn({ data }),
+    mutationFn: (data: { title: string; content: string }) => createPost({ data }),
     onSuccess: () => {
       // 관련 쿼리 무효화로 데이터 동기화
       queryClient.invalidateQueries({ queryKey: ['posts'] })
@@ -181,6 +176,92 @@ function BadExample() {
 }
 ```
 
+## ⚠️ 함수 분리 시 유의사항
+
+Server Function 내부 로직을 별도 함수로 분리할 때 반드시 아래 규칙을 따르세요.
+
+### 규칙
+
+```
+1. 분리한 함수는 createServerFn 내부에서만 호출
+2. 분리한 함수는 createServerFn으로 감싸지 않음
+3. 분리한 함수는 index.ts에서 export 금지 (프론트엔드 import 방지)
+```
+
+### ✅ 올바른 패턴
+
+```typescript
+// services/user/mutations.ts
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 내부 헬퍼 함수 (export 금지!)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+const validateUserData = async (email: string) => {
+  const existing = await prisma.user.findUnique({ where: { email } })
+  if (existing) throw new Error('Email already exists')
+  return true
+}
+
+const sendWelcomeEmail = async (userId: string, email: string) => {
+  await emailService.send({
+    to: email,
+    template: 'welcome',
+    data: { userId },
+  })
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Server Function (export 가능)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator(createUserSchema)
+  .handler(async ({ data }) => {
+    // 내부 헬퍼 함수 호출
+    await validateUserData(data.email)
+
+    const user = await prisma.user.create({ data })
+
+    // 내부 헬퍼 함수 호출
+    await sendWelcomeEmail(user.id, user.email)
+
+    return user
+  })
+```
+
+```typescript
+// services/user/index.ts
+
+// ✅ Server Function만 export
+export { createUser, updateUser, deleteUser } from './mutations'
+export { getUsers, getUserById } from './queries'
+
+// ❌ 내부 헬퍼 함수는 export 금지!
+// export { validateUserData, sendWelcomeEmail } from './mutations'
+```
+
+### ❌ 잘못된 패턴
+
+```typescript
+// ❌ 분리한 함수를 createServerFn으로 감싸지 마세요
+export const validateUserData = createServerFn({ method: 'POST' })
+  .handler(async ({ data }) => {
+    // ...
+  })
+
+// ❌ 내부 헬퍼 함수를 export 하지 마세요
+export const sendWelcomeEmail = async (userId: string) => {
+  // 프론트엔드에서 import 가능해져 보안 위험!
+}
+```
+
+### 이유
+
+- **보안**: 내부 로직이 프론트엔드 번들에 포함되지 않음
+- **명확한 API**: Server Function만 외부에 노출되어 API 경계가 명확함
+- **트리 쉐이킹**: export하지 않은 함수는 번들에서 제거됨
+
+---
+
 ## 보안 패턴
 
 ### 서버 전용 데이터 보호

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

@@ -45,7 +45,7 @@ export default defineConfig({
     "jsx": "react-jsx",
     "baseUrl": ".",
     "paths": {
-      "~/*": ["./src/*"]
+      "@/*": ["./src/*"]
     }
   },
   "include": ["src/**/*"]