---
name: dev-docs
description: |
  Nuxt 3 공식 문서 기반의 Best Practice 코드를 생성합니다.
  server/, middleware/, plugins/, composables/, components/, nuxt.config 등
  6개 참조 영역에서 상황에 맞는 패턴을 선택해 즉시 사용 가능한 코드를 제공합니다.

  다음 상황에서 반드시 사용하세요:
  - "Nuxt server route 만들어줘", "composable 작성해줘"
  - "middleware 어떻게 써?", "Nuxt에서 이 기능 어떻게 구현해?"
  - 공식 문서를 찾아보지 않고 Nuxt 3 패턴 코드가 필요할 때
---

# Nuxt 3 공식 문서 기반 개발 (dev-docs)

Nuxt 3 공식 Best Practice를 기반으로 즉시 사용 가능한 코드를 생성합니다.

## 언제 사용하는가

- Nuxt 고유 API(useAsyncData, useFetch, defineEventHandler 등)를 처음 사용할 때
- server/, middleware/, plugins/ 등 Nuxt 레이어 구현이 필요할 때
- 공식 문서를 찾는 대신 곧바로 Best Practice 코드를 얻고 싶을 때

## 참조 영역

| 영역 | 경로 | 주요 API |
|---|---|---|
| Server Routes | `server/api/`, `server/routes/` | `defineEventHandler`, `readBody`, `getQuery` |
| Middleware | `middleware/` | `defineNuxtRouteMiddleware`, `navigateTo` |
| Plugins | `plugins/` | `defineNuxtPlugin`, `useNuxtApp` |
| Composables | `composables/` | `useState`, `useFetch`, `useAsyncData` |
| Components | `components/` | auto-import, `<ClientOnly>`, `<LazyLoad>` |
| Config | `nuxt.config.ts` | `runtimeConfig`, `modules`, `routeRules` |

---

## 작업 순서

### Phase 1: 요구사항 분석

1. 사용자 요청에서 구현 영역을 파악한다.
   - "API 만들어줘" → `server/api/`
   - "인증 체크" → `middleware/`
   - "전역 상태" → `composables/` + `useState`
   - "외부 라이브러리 초기화" → `plugins/`

2. 관련 Nuxt 3 API를 선택한다.

### Phase 2: 코드 생성

#### Server Route 예시
```ts
// server/api/users/[id].get.ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  // 비즈니스 로직
  return { data }
})
```

#### Middleware 예시
```ts
// middleware/auth.ts
export default defineNuxtRouteMiddleware((to) => {
  const { isAuthenticated } = useAuth()
  if (!isAuthenticated.value) {
    return navigateTo('/login')
  }
})
```

#### Composable 예시
```ts
// composables/useUser.ts
export const useUser = () => {
  const user = useState<User | null>('user', () => null)

  const fetchUser = async (id: string) => {
    const { data } = await useFetch<User>(`/api/users/${id}`)
    user.value = data.value
  }

  return { user, fetchUser }
}
```

### Phase 3: TypeScript 타입 보강

- 모든 함수 파라미터/반환값 타입 명시
- 외부 API 응답은 `types/` 또는 해당 도메인의 `types.ts`에 정의
- `runtimeConfig`는 `RuntimeConfig` 타입 확장으로 타입 안전성 확보

### Phase 4: 연관 설정 안내

생성된 코드에 필요한 `nuxt.config.ts` 변경사항이 있으면 함께 안내한다.

```ts
// nuxt.config.ts 필요 설정 예시
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', // 서버 전용
    public: {
      apiBase: '' // 클라이언트 노출 가능
    }
  }
})
```

---

## 출력 형식

```
## Nuxt 구현: <기능명>

### 사용 패턴
- 영역: server/api/ | middleware/ | composables/ | ...
- 주요 API: defineEventHandler, useFetch, ...

### 코드
[파일별 코드]

### nuxt.config.ts 변경 필요 사항
[있는 경우만]

### 주의사항
[SSR/CSR 차이, 캐시 주의 등]
```