@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/fe/sources/vue/nuxt-data-fetching.md

@@ -0,0 +1,232 @@
+---
+title: Nuxt 3 데이터 페칭 (useFetch / useAsyncData / SSR hydration)
+source: https://nuxt.com/docs/getting-started/data-fetching
+fetched: 2026-05-18
+category: nuxt
+vue_version: 3
+---
+
+# Nuxt 3 데이터 페칭 완전 가이드
+
+---
+
+## 핵심 도구 3가지
+
+| 도구 | 용도 |
+|------|------|
+| `$fetch` | 클라이언트 사이드 단순 요청 |
+| `useFetch` | SSR-safe 초기 데이터 페칭 (most common) |
+| `useAsyncData` | 세밀한 제어가 필요할 때 |
+
+---
+
+## 왜 useFetch/useAsyncData가 필요한가?
+
+유니버설 렌더링 환경에서 `$fetch`를 setup에서 직접 호출하면 서버와 클라이언트에서 **두 번 실행**된다. → hydration mismatch, 불필요한 네트워크 요청 발생.
+
+`useFetch`/`useAsyncData`는 서버에서 페칭한 데이터를 payload에 담아 클라이언트로 전달하여 재요청을 방지한다.
+
+```
+useNuxtApp().payload  ← 서버 → 클라이언트 데이터 전달 경로
+```
+
+---
+
+## $fetch
+
+```vue
+<script setup lang="ts">
+async function addTodo() {
+  const todo = await $fetch('/api/todos', {
+    method: 'POST',
+    body: { /* todo data */ }
+  })
+}
+</script>
+```
+
+**주의:** `$fetch` 단독 사용 시 deduplication과 navigation blocking이 없다. 초기 페이지 데이터에는 사용 금지.
+
+---
+
+## useFetch
+
+```vue
+<script setup lang="ts">
+const { data: count } = await useFetch('/api/count')
+</script>
+
+<template>
+  <p>Page visits: {{ count }}</p>
+</template>
+```
+
+`useFetch(url)` ≈ `useAsyncData(url, () => event.$fetch(url))` — 가장 흔한 패턴의 syntactic sugar.
+
+---
+
+## useAsyncData
+
+CMS나 서드파티 쿼리 레이어를 사용할 때 적합하다.
+
+```vue
+<script setup lang="ts">
+const { data, error } = await useAsyncData('users', () => myGetFunction('users'))
+</script>
+```
+
+**병렬 요청:**
+```ts
+const { data } = await useAsyncData((_nuxtApp, { signal }) => {
+  return Promise.all([
+    $fetch('/api/comments', { signal }),
+    $fetch('/api/author/12', { signal }),
+  ])
+})
+const comments = computed(() => data.value?.[0])
+const author = computed(() => data.value?.[1])
+```
+
+**중요:** `useAsyncData`는 Pinia action 호출 등 사이드 이펙트 트리거용이 아니다. 반복 실행 위험이 있으므로 `callOnce`를 사용한다.
+
+---
+
+## 반환값
+
+```ts
+const {
+  data,      // 결과 ref
+  refresh,   // 수동 재요청
+  execute,   // 수동 실행 (immediate: false 시)
+  clear,     // data를 undefined로 리셋
+  error,     // 에러 객체
+  status,    // 'idle' | 'pending' | 'success' | 'error'
+} = useFetch('/api/users')
+```
+
+---
+
+## 주요 옵션
+
+### lazy (비차단 페칭)
+
+```vue
+<script setup lang="ts">
+const { status, data: posts } = useFetch('/api/posts', { lazy: true })
+</script>
+
+<template>
+  <div v-if="status === 'pending'">Loading...</div>
+  <div v-else>...</div>
+</template>
+```
+
+단축형: `useLazyFetch`, `useLazyAsyncData`
+
+### server: false (클라이언트 전용)
+
+```ts
+const { data: comments } = useFetch('/api/comments', {
+  lazy: true,
+  server: false,
+})
+```
+
+### pick / transform (페이로드 최소화)
+
+```ts
+// pick: 특정 필드만 선택
+const { data: mountain } = await useFetch('/api/mountains/everest', {
+  pick: ['title', 'description'],
+})
+
+// transform: 변환 함수
+const { data: mountains } = await useFetch('/api/mountains', {
+  transform: (mountains) =>
+    mountains.map((m) => ({ title: m.title, description: m.description }))
+})
+```
+
+### watch (반응형 재실행)
+
+```ts
+const id = ref(1)
+const { data } = await useFetch('/api/users', { watch: [id] })
+```
+
+### computed URL (동적 URL)
+
+```vue
+<script setup lang="ts">
+const id = ref(null)
+const { data, status } = useLazyFetch(() => `/api/users/${id.value}`, {
+  immediate: false,
+})
+</script>
+```
+
+### immediate: false (수동 실행)
+
+```vue
+<script setup lang="ts">
+const { data, execute, status } = await useLazyFetch('/api/comments', {
+  immediate: false,
+})
+</script>
+<template>
+  <div v-if="status === 'idle'">
+    <button @click="execute">Get data</button>
+  </div>
+  <div v-else-if="status === 'pending'">Loading...</div>
+  <div v-else>{{ data }}</div>
+</template>
+```
+
+---
+
+## SSR 헤더 & 쿠키
+
+**브라우저 요청:** 쿠키가 `$fetch`에 자동 포함.
+
+**서버 사이드:** `useFetch`는 `useRequestFetch`로 클라이언트 헤더/쿠키를 자동 프록시.
+
+수동 전달:
+```vue
+<script setup lang="ts">
+const headers = useRequestHeaders(['cookie'])
+const user = await $fetch('/api/me', { headers })
+</script>
+```
+
+**절대 프록시하면 안 되는 헤더:** `host`, `accept`, `content-length`, `content-md5`, `content-type`, `x-forwarded-*`, `cf-connecting-ip`, `cf-ray`
+
+---
+
+## 데이터 직렬화
+
+### useAsyncData (서버→클라이언트): `devalue` 사용
+- 지원 타입: 기본 JSON + RegExp, Date, Map, Set, Vue ref, NuxtError
+
+### 서버 API 라우트: `JSON.stringify` 사용
+- Date 등 복잡한 타입 직렬화 시 `toJSON()` 또는 `superjson` 활용 필요
+
+```ts
+// 서버
+export default defineEventHandler(() => ({
+  createdAt: new Date(),
+  toJSON() {
+    return { createdAt: { year: this.createdAt.getFullYear(), /* ... */ } }
+  }
+}))
+```
+
+---
+
+## 핵심 요약
+
+1. 클라이언트 인터랙션 → `$fetch`
+2. 초기 페이지 데이터 → `useFetch`
+3. CMS/서드파티 API → `useAsyncData`
+4. navigation 비차단 → `lazy: true` 또는 `useLazyFetch`
+5. 캐시 키를 custom composable에서 명시적으로 지정
+6. 동적 URL은 computed 함수 형태로 전달

package/assets/dev-guide/fe/sources/vue/pinia-state-management.md

@@ -0,0 +1,134 @@
+---
+title: Pinia 상태 관리 패턴
+source: https://pinia.vuejs.org/core-concepts/
+fetched: 2026-05-18
+category: state
+vue_version: 3
+---
+
+# Pinia 상태 관리 핵심 개념
+
+---
+
+## Store 정의
+
+`defineStore()`로 생성하며 고유한 id가 필요하다. 관례적으로 `use`로 시작하고 `Store`로 끝내는 이름을 사용한다.
+
+```js
+import { defineStore } from 'pinia'
+export const useAlertsStore = defineStore('alerts', { /* ... */ })
+```
+
+---
+
+## 두 가지 문법
+
+### Option Store (Options API 스타일)
+
+```js
+export const useCounterStore = defineStore('counter', {
+  state: () => ({ count: 0, name: 'Eduardo' }),
+  getters: {
+    doubleCount: (state) => state.count * 2,
+  },
+  actions: {
+    increment() {
+      this.count++
+    },
+  },
+})
+```
+
+| Pinia | Vue Options API |
+|-------|----------------|
+| `state` | `data` |
+| `getters` | `computed` |
+| `actions` | `methods` |
+
+### Setup Store (Composition API 스타일)
+
+```js
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0)
+  const name = ref('Eduardo')
+  const doubleCount = computed(() => count.value * 2)
+
+  function increment() {
+    count.value++
+  }
+
+  return { count, name, doubleCount, increment }
+})
+```
+
+| Composition API | Pinia 매핑 |
+|-----------------|-----------|
+| `ref()` | state |
+| `computed()` | getters |
+| `function` | actions |
+
+**주의:** 모든 state 속성은 반드시 반환해야 한다. 미반환 시 SSR, devtools, 플러그인이 정상 동작하지 않는다.
+
+Setup Store에서 외부 의존성 주입:
+```ts
+import { inject } from 'vue'
+import { useRoute } from 'vue-router'
+
+export const useSearchFilters = defineStore('search-filters', () => {
+  const route = useRoute()
+  const appProvided = inject('appProvided')  // inject 값은 반환하지 않는다
+  return { /* ... */ }
+})
+```
+
+---
+
+## Store 사용
+
+```vue
+<script setup>
+import { useCounterStore } from '@/stores/counter'
+
+const store = useCounterStore()
+</script>
+```
+
+store 객체는 반응형이므로 `.value` 불필요. 단, 직접 구조 분해 시 반응성이 끊긴다.
+
+```vue
+<script setup>
+const store = useCounterStore()
+
+// ❌ 반응성 손실
+const { name, doubleCount } = store
+
+// ✅ 반응성 유지
+const doubleValue = computed(() => store.doubleCount)
+</script>
+```
+
+---
+
+## storeToRefs()로 반응형 구조 분해
+
+```vue
+<script setup>
+import { useCounterStore } from '@/stores/counter'
+import { storeToRefs } from 'pinia'
+
+const store = useCounterStore()
+
+// state/getters: storeToRefs 사용
+const { name, doubleCount } = storeToRefs(store)
+
+// actions: 직접 구조 분해 가능
+const { increment } = store
+</script>
+```
+
+---
+
+## 문법 선택 가이드
+
+- **Option Store**: 단순하고 입문자에게 친화적
+- **Setup Store**: 복잡한 로직, watchers, composables 활용 시 더 강력하지만 SSR 복잡도 증가

package/assets/dev-guide/fe/sources/vue/reactivity-pitfalls.md

@@ -0,0 +1,261 @@
+---
+title: Vue 3 반응성 함정 (Reactivity Pitfalls)
+source: https://vuejs.org/guide/extras/reactivity-in-depth.html
+fetched: 2026-05-18
+category: reactivity
+vue_version: 3
+---
+
+# Vue 3 반응성 심층 가이드
+
+---
+
+## 반응성의 작동 원리
+
+Vue는 두 가지 방식으로 객체 속성 접근을 가로챈다:
+
+1. **Proxy** (Vue 3 `reactive()`)
+2. **Getter/Setter** (Vue 3 `ref()`)
+
+```js
+function reactive(obj) {
+  return new Proxy(obj, {
+    get(target, key) {
+      track(target, key)      // 의존성 추적
+      return target[key]
+    },
+    set(target, key, value) {
+      target[key] = value
+      trigger(target, key)    // 구독자 알림
+    }
+  })
+}
+
+function ref(value) {
+  const refObject = {
+    get value() {
+      track(refObject, 'value')
+      return value
+    },
+    set value(newValue) {
+      value = newValue
+      trigger(refObject, 'value')
+    }
+  }
+  return refObject
+}
+```
+
+### 핵심 메커니즘
+
+```js
+let activeEffect  // 현재 실행 중인 effect
+
+function track(target, key) {
+  if (activeEffect) {
+    const effects = getSubscribersForProperty(target, key)
+    effects.add(activeEffect)
+  }
+}
+
+function trigger(target, key) {
+  const effects = getSubscribersForProperty(target, key)
+  effects.forEach((effect) => effect())
+}
+```
+
+---
+
+## ref vs reactive 선택 가이드
+
+| 상황 | 권장 |
+|------|------|
+| 원시값 (string, number, boolean) | `ref()` |
+| 객체/배열의 전체 재할당 필요 | `ref()` |
+| 객체의 속성만 변경 | `reactive()` 또는 `ref()` |
+| 컴포저블/스토어 반환값 | `ref()` (구조 분해 가능) |
+
+---
+
+## 반응성 함정 (Pitfalls)
+
+### 1. reactive() 구조 분해 시 반응성 손실
+
+```js
+const state = reactive({ count: 0 })
+
+// ❌ BROKEN: 구조 분해 후 반응성 끊김
+const { count } = state
+count++  // state.count에 반영되지 않음
+
+// ✅ WORKS: 직접 접근
+state.count++
+```
+
+**비원시 값은 예외 (객체 참조 공유):**
+```js
+const state = reactive({ user: { name: 'John' } })
+
+// ✅ WORKS: 객체 참조 공유이므로 변경이 추적됨
+const { user } = state
+user.name = 'Jane'  // state.user.name도 변경됨
+```
+
+### 2. props 구조 분해 시 반응성 손실 (Vue 3.5 이전)
+
+```vue
+<script setup>
+const props = defineProps({ count: Number })
+
+// ❌ Vue 3.4 이하: 반응성 손실
+const { count } = props
+watchEffect(() => console.log(count))  // count 변경 감지 안 됨
+
+// ✅ 올바른 방법
+watchEffect(() => console.log(props.count))
+
+// ✅ Vue 3.5+: 반응형 구조 분해 지원
+const { count } = defineProps(['count'])  // 이제 반응형
+</script>
+```
+
+### 3. Proxy 동일성 문제
+
+```js
+const original = {}
+const reactive_obj = reactive(original)
+
+console.log(original === reactive_obj)  // false ← Proxy이므로 다름
+```
+
+**항상 reactive 버전으로만 작업해야 한다.**
+
+---
+
+## 반응성 디버깅
+
+### 컴포넌트 디버그 훅
+
+```js
+import { onRenderTracked, onRenderTriggered } from 'vue'
+
+onRenderTracked((event) => {
+  debugger  // 의존성 추적 시점
+})
+
+onRenderTriggered((event) => {
+  debugger  // 의존성 변경 → 리렌더 시점
+})
+```
+
+**DebuggerEvent 구조:**
+```ts
+type DebuggerEvent = {
+  effect: ReactiveEffect
+  target: object
+  type: 'get' | 'has' | 'iterate' | 'set' | 'add' | 'delete' | 'clear'
+  key: any
+  newValue?: any
+  oldValue?: any
+}
+```
+
+### computed 디버깅
+
+```js
+const plusOne = computed(() => count.value + 1, {
+  onTrack(e) {
+    debugger  // 의존성 추적 시
+  },
+  onTrigger(e) {
+    debugger  // 의존성 변경 시
+  }
+})
+```
+
+### watcher 디버깅
+
+```js
+watch(source, callback, {
+  onTrack(e) { debugger },
+  onTrigger(e) { debugger }
+})
+
+watchEffect(callback, {
+  onTrack(e) { debugger },
+  onTrigger(e) { debugger }
+})
+```
+
+---
+
+## 외부 상태 시스템 연동
+
+외부 라이브러리 상태는 `shallowRef()`를 사용한다. 깊은 변환을 피한다.
+
+```js
+import { shallowRef } from 'vue'
+
+const externalState = shallowRef(externalLibrary.state)
+// 외부 상태 변경 시 ref 값을 교체
+externalState.value = newExternalState
+```
+
+**Immer와 연동:**
+```js
+import { produce } from 'immer'
+import { shallowRef } from 'vue'
+
+export function useImmer(baseState) {
+  const state = shallowRef(baseState)
+  const update = (updater) => {
+    state.value = produce(state.value, updater)
+  }
+  return [state, update]
+}
+```
+
+---
+
+## 런타임 vs 컴파일 타임 반응성
+
+| 방식 | 예시 | 장점 | 단점 |
+|------|------|------|------|
+| **런타임** (Vue) | `ref()`, `reactive()` | 빌드 불필요, 엣지 케이스 적음 | `.value` 필요, JS 문법 제약 |
+| **컴파일 타임** (Svelte) | `let count = 0` (컴파일러 변환) | 더 나은 ergonomics | 빌드 필수, JS 의미론 변경 |
+
+Vue는 Reactivity Transform 실험 후 컴파일 타임 방식을 채택하지 않기로 결정했다.
+
+---
+
+## Signal 패턴 (참고)
+
+다른 프레임워크의 signal 패턴을 Vue로 구현할 수 있다.
+
+**Solid.js 스타일:**
+```js
+import { shallowRef, triggerRef } from 'vue'
+
+function createSignal(value, options) {
+  const r = shallowRef(value)
+  const get = () => r.value
+  const set = (v) => {
+    r.value = typeof v === 'function' ? v(r.value) : v
+    if (options?.equals === false) triggerRef(r)
+  }
+  return [get, set]
+}
+```
+
+**Angular 스타일:**
+```js
+import { shallowRef } from 'vue'
+
+function signal(initialValue) {
+  const r = shallowRef(initialValue)
+  const s = () => r.value
+  s.set = (value) => { r.value = value }
+  s.update = (updater) => { r.value = updater(r.value) }
+  return s
+}
+```