@kood/claude-code 0.1.0

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

@@ -0,0 +1,146 @@
+# TanStack Query - Query 무효화
+
+> **상위 문서**: [TanStack Query](./index.md)
+
+## 기본 무효화
+
+```typescript
+const queryClient = useQueryClient()
+
+// 단일 쿼리 무효화
+await queryClient.invalidateQueries({ queryKey: ['todos'] })
+
+// 다중 쿼리 무효화
+await Promise.all([
+  queryClient.invalidateQueries({ queryKey: ['todos'] }),
+  queryClient.invalidateQueries({ queryKey: ['reminders'] }),
+])
+
+// 모든 쿼리 무효화
+queryClient.invalidateQueries()
+```
+
+## 무효화 옵션
+
+```typescript
+await queryClient.invalidateQueries(
+  {
+    queryKey: ['posts'],
+    exact: true, // 정확한 키 매칭만
+    refetchType: 'active', // 'active' | 'inactive' | 'all' | 'none'
+  },
+  {
+    throwOnError: false,
+    cancelRefetch: true,
+  }
+)
+```
+
+## refetchType 옵션
+
+- `active`: 현재 렌더링 중인 쿼리만 재조회 (기본값)
+- `inactive`: 비활성 쿼리만 재조회
+- `all`: 모든 매칭 쿼리 재조회
+- `none`: 무효화만 하고 재조회 안 함
+
+## Query Key로 무효화
+
+```typescript
+// 'todos'로 시작하는 모든 쿼리 무효화
+queryClient.invalidateQueries({ queryKey: ['todos'] })
+
+// 정확히 ['todos', 'list']인 쿼리만 무효화
+queryClient.invalidateQueries({
+  queryKey: ['todos', 'list'],
+  exact: true,
+})
+
+// ['todos', { type: 'done' }] 무효화
+queryClient.invalidateQueries({
+  queryKey: ['todos', { type: 'done' }],
+})
+```
+
+## Mutation과 함께 사용
+
+### onSuccess에서 무효화
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+function TodosComponent() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: addTodo,
+    onSuccess: async () => {
+      // 단일 쿼리 무효화
+      await queryClient.invalidateQueries({ queryKey: ['todos'] })
+
+      // 여러 쿼리 무효화
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: ['todos'] }),
+        queryClient.invalidateQueries({ queryKey: ['reminders'] }),
+      ])
+    },
+  })
+
+  return (
+    <button onClick={() => mutation.mutate(newTodo)}>
+      Add Todo
+    </button>
+  )
+}
+```
+
+### onSettled에서 무효화
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onSettled: () => {
+    // 성공/실패 관계없이 무효화
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+## 캐시 직접 업데이트 vs 무효화
+
+```tsx
+// 방법 1: 캐시 직접 업데이트 (더 빠름)
+queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+
+// 방법 2: 무효화 후 재조회 (서버 데이터 보장)
+queryClient.invalidateQueries({ queryKey: ['todos'] })
+```
+
+## 조건부 무효화
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onSuccess: (data, variables) => {
+    // 특정 조건에서만 무효화
+    if (variables.category === 'important') {
+      queryClient.invalidateQueries({ queryKey: ['todos', 'important'] })
+    }
+
+    // 항상 개별 항목은 무효화
+    queryClient.invalidateQueries({ queryKey: ['todo', variables.id] })
+  },
+})
+```
+
+## prefetch와 조합
+
+```tsx
+// 무효화 전에 새 데이터 프리페치
+await queryClient.prefetchQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+// 이후 무효화 시 이미 새 데이터가 있음
+queryClient.invalidateQueries({ queryKey: ['todos'] })
+```

package/templates/tanstack-start/docs/library/tanstack-query/optimistic-updates.md

@@ -0,0 +1,196 @@
+# TanStack Query - Optimistic Updates
+
+> **상위 문서**: [TanStack Query](./index.md)
+
+낙관적 업데이트는 서버 응답을 기다리지 않고 UI를 즉시 업데이트하는 패턴입니다.
+
+## 기본 패턴
+
+```tsx
+const addTodoMutation = useMutation({
+  mutationFn: (newTodo: string) => axios.post('/api/data', { text: newTodo }),
+  // mutation 완료 후 쿼리 무효화
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+})
+
+const { isPending, submittedAt, variables, mutate, isError } = addTodoMutation
+```
+
+## 완전한 Optimistic Update 패턴
+
+```tsx
+type Todo = { id: string; text: string }
+type TodosResponse = { items: Todo[]; ts: number }
+
+function TodoList() {
+  const queryClient = useQueryClient()
+  const [text, setText] = React.useState('')
+
+  const addTodoMutation = useMutation({
+    mutationFn: async (newTodo: string): Promise<Todo> => {
+      const response = await fetch('/api/todos', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ text: newTodo }),
+      })
+      return response.json()
+    },
+    onMutate: async (newTodo) => {
+      // 1. 진행 중인 refetch 취소 (optimistic update 덮어쓰기 방지)
+      await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+      // 2. 롤백을 위한 이전 값 스냅샷
+      const previousTodos = queryClient.getQueryData<TodosResponse>(['todos'])
+
+      // 3. 캐시 optimistic 업데이트
+      if (previousTodos) {
+        queryClient.setQueryData<TodosResponse>(['todos'], {
+          ...previousTodos,
+          items: [
+            ...previousTodos.items,
+            { id: Math.random().toString(), text: newTodo },
+          ],
+        })
+      }
+
+      // 4. context로 이전 값 반환
+      return { previousTodos }
+    },
+    onError: (err, variables, context) => {
+      // 5. 에러 시 롤백
+      if (context?.previousTodos) {
+        queryClient.setQueryData(['todos'], context.previousTodos)
+      }
+    },
+    onSettled: () => {
+      // 6. 서버와 캐시 동기화를 위해 refetch
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <div>
+      <form onSubmit={(e) => {
+        e.preventDefault()
+        addTodoMutation.mutate(text)
+        setText('')
+      }}>
+        <input value={text} onChange={(e) => setText(e.target.value)} />
+        <button type="submit" disabled={addTodoMutation.isPending}>
+          {addTodoMutation.isPending ? 'Adding...' : 'Add Todo'}
+        </button>
+      </form>
+      {addTodoMutation.isError && <div>Error: {addTodoMutation.error.message}</div>}
+    </div>
+  )
+}
+```
+
+## 단일 항목 Optimistic Update
+
+```tsx
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // 진행 중인 refetch 취소
+    await queryClient.cancelQueries({ queryKey: ['todos', newTodo.id] })
+
+    // 이전 값 스냅샷
+    const previousTodo = queryClient.getQueryData(['todos', newTodo.id])
+
+    // Optimistic 업데이트
+    queryClient.setQueryData(['todos', newTodo.id], newTodo)
+
+    return { previousTodo, newTodo }
+  },
+  onError: (err, newTodo, context) => {
+    // 에러 시 롤백
+    queryClient.setQueryData(
+      ['todos', context.newTodo.id],
+      context.previousTodo,
+    )
+  },
+  onSettled: (newTodo) => {
+    queryClient.invalidateQueries({ queryKey: ['todos', newTodo.id] })
+  },
+})
+```
+
+## 삭제 Optimistic Update
+
+```tsx
+const deleteMutation = useMutation({
+  mutationFn: (todoId: string) => deleteTodo(todoId),
+  onMutate: async (todoId) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+    const previousTodos = queryClient.getQueryData<Todo[]>(['todos'])
+
+    // 삭제된 항목 제외
+    queryClient.setQueryData<Todo[]>(['todos'], (old) =>
+      old?.filter((todo) => todo.id !== todoId)
+    )
+
+    return { previousTodos }
+  },
+  onError: (err, todoId, context) => {
+    queryClient.setQueryData(['todos'], context?.previousTodos)
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+## 토글 Optimistic Update
+
+```tsx
+const toggleMutation = useMutation({
+  mutationFn: (todoId: string) => toggleTodo(todoId),
+  onMutate: async (todoId) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+    const previousTodos = queryClient.getQueryData<Todo[]>(['todos'])
+
+    // 토글 상태 변경
+    queryClient.setQueryData<Todo[]>(['todos'], (old) =>
+      old?.map((todo) =>
+        todo.id === todoId
+          ? { ...todo, completed: !todo.completed }
+          : todo
+      )
+    )
+
+    return { previousTodos }
+  },
+  onError: (err, todoId, context) => {
+    queryClient.setQueryData(['todos'], context?.previousTodos)
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+## Persist (영속성)
+
+### Optimistic Update 즉시 저장
+
+```tsx
+const persister = experimental_createQueryPersister({
+  storage: AsyncStorage,
+  maxAge: 1000 * 60 * 60 * 12, // 12시간
+})
+
+const queryClient = useQueryClient()
+
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // Optimistic 업데이트
+    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+    // 즉시 스토리지에 저장
+    persister.persistQueryByKey(['todos'], queryClient)
+  },
+})
+```

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

@@ -0,0 +1,110 @@
+# TanStack Query - 설치 및 설정
+
+> **상위 문서**: [TanStack Query](./index.md)
+
+## 설치
+
+```bash
+yarn add @tanstack/react-query
+```
+
+## QueryClient 설정
+
+```tsx
+import {
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
+
+// QueryClient 생성
+const queryClient = new QueryClient()
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+    </QueryClientProvider>
+  )
+}
+```
+
+## QueryClient 옵션
+
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5, // 5분
+      gcTime: 1000 * 60 * 30, // 30분 (이전의 cacheTime)
+      retry: 3,
+      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+      refetchOnWindowFocus: true,
+      refetchOnReconnect: true,
+    },
+    mutations: {
+      retry: 1,
+    },
+  },
+})
+```
+
+## TanStack Start와 함께 사용
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+import { useServerFn } from '@tanstack/react-start'
+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>
+  )
+}
+```
+
+## Query Keys 패턴
+
+```typescript
+// 간단한 키
+['todos']
+
+// 파라미터가 있는 키
+['todo', { id: 5 }]
+
+// 계층적 키
+['todos', 'list', { filters: 'all' }]
+['todos', 'detail', todoId]
+```
+
+## DevTools (개발용)
+
+```bash
+yarn add @tanstack/react-query-devtools
+```
+
+```tsx
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  )
+}
+```

package/templates/tanstack-start/docs/library/tanstack-query/use-mutation.md

@@ -0,0 +1,170 @@
+# TanStack Query - useMutation
+
+> **상위 문서**: [TanStack Query](./index.md)
+
+## 기본 사용법
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+function AddTodo() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: postTodo,
+    onSuccess: () => {
+      // 성공 시 todos 쿼리 무효화하여 재조회
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button
+      onClick={() => {
+        mutation.mutate({
+          id: Date.now(),
+          title: 'Do Laundry',
+        })
+      }}
+    >
+      Add Todo
+    </button>
+  )
+}
+```
+
+## useMutation 반환 값
+
+```typescript
+const {
+  data,           // mutation 결과 데이터
+  error,          // 에러 객체
+  isError,        // 에러 상태
+  isIdle,         // 아직 실행 안 됨
+  isPending,      // 실행 중
+  isPaused,       // 일시 정지됨
+  isSuccess,      // 성공 상태
+  failureCount,   // 실패 횟수
+  failureReason,  // 실패 이유
+  mutate,         // mutation 실행 (비동기)
+  mutateAsync,    // mutation 실행 (Promise 반환)
+  reset,          // 상태 초기화
+  status,         // 'idle' | 'pending' | 'success' | 'error'
+  submittedAt,    // 제출 시간
+  variables,      // 전달된 변수
+} = useMutation({ mutationFn })
+```
+
+## useMutation 옵션
+
+```tsx
+const mutation = useMutation({
+  mutationFn,
+  gcTime,             // 가비지 컬렉션 시간
+  meta,               // 메타데이터
+  mutationKey,        // mutation 키
+  networkMode,        // 네트워크 모드
+  onError,            // 에러 콜백
+  onMutate,           // mutation 시작 전 콜백
+  onSettled,          // 완료 후 콜백 (성공/실패 무관)
+  onSuccess,          // 성공 콜백
+  retry,              // 재시도 횟수
+  retryDelay,         // 재시도 딜레이
+  scope,              // 범위
+  throwOnError,       // 에러 throw 여부
+})
+```
+
+## 콜백 함수들
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // mutation 시작 전 실행
+    console.log('Starting mutation with:', newTodo)
+    return { previousData: 'something' } // context로 전달
+  },
+  onSuccess: (data, variables, context) => {
+    // 성공 시 실행
+    console.log('Success:', data)
+    console.log('Variables:', variables)
+    console.log('Context:', context)
+  },
+  onError: (error, variables, context) => {
+    // 에러 시 실행
+    console.log('Error:', error)
+    // context로 롤백 가능
+  },
+  onSettled: (data, error, variables, context) => {
+    // 성공/실패 무관하게 완료 시 실행
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+## mutate vs mutateAsync
+
+```tsx
+// mutate - 콜백 기반
+mutation.mutate(data, {
+  onSuccess: (result) => {
+    console.log('Success:', result)
+  },
+  onError: (error) => {
+    console.log('Error:', error)
+  },
+})
+
+// mutateAsync - Promise 기반
+try {
+  const result = await mutation.mutateAsync(data)
+  console.log('Success:', result)
+} catch (error) {
+  console.log('Error:', error)
+}
+```
+
+## Error 상태 Reset
+
+```tsx
+const CreateTodo = () => {
+  const [title, setTitle] = useState('')
+  const mutation = useMutation({ mutationFn: createTodo })
+
+  const onCreateTodo = (e) => {
+    e.preventDefault()
+    mutation.mutate({ title })
+  }
+
+  return (
+    <form onSubmit={onCreateTodo}>
+      {mutation.error && (
+        <h5 onClick={() => mutation.reset()}>{mutation.error}</h5>
+      )}
+      <input
+        type="text"
+        value={title}
+        onChange={(e) => setTitle(e.target.value)}
+      />
+      <br />
+      <button type="submit">Create Todo</button>
+    </form>
+  )
+}
+```
+
+## 캐시 직접 업데이트
+
+```tsx
+const saveMutation = useMutation({
+  mutationFn: patchTodo,
+  onSuccess: (data) => {
+    // 목록 쿼리 무효화
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+
+    // 개별 항목 캐시 직접 업데이트
+    queryClient.setQueryData(['todo', { id: data.id }], data)
+  },
+})
+```