---
description:  Vue 3 프론트엔드 개발 규칙
---

> 이 파일은 `.claude/commands/vue3.md`에 위치한다.
> 사용법: `/vue3 [요청 내용]`

---

## 컴포넌트 작성 원칙

### 필수 구조

```vue
<script setup lang="ts">
// 1. import
// 2. Props / Emits 정의
// 3. Store / Composable 호출
// 4. 반응형 상태 (ref, reactive, computed)
// 5. 함수 정의
// 6. Lifecycle Hooks
// 7. watch
</script>

<template>
  <!-- 시맨틱 HTML 태그 사용 -->
</template>

<style scoped>
/* rem 단위 사용, 인라인 스타일 금지 */
</style>
```

- `Options API` 사용 **금지** → `Composition API` + `<script setup>` 필수
- 인라인 스타일(`style=""`) 사용 **금지** → `<style scoped>` 사용
- 모든 px 값은 **rem으로 변환** (기준: 16px = 1rem)

---

## Props / Emits 타입 정의

```typescript
// Props
interface Props {
  title: string
  count?: number
  items: string[]
}
const props = withDefaults(defineProps<Props>(), {
  count: 0,
})

// Emits
interface Emits {
  (e: 'update', value: string): void
  (e: 'close'): void
}
const emit = defineEmits<Emits>()
```

---

## 상태 관리 (Pinia)

```typescript
// stores/user.store.ts
export const useUserStore = defineStore('user', () => {
  // 상태
  const user = ref<User | null>(null)
  const isLoggedIn = computed(() => !!user.value)

  // 액션
  async function fetchUser(id: number) {
    // API 호출
  }

  return { user, isLoggedIn, fetchUser }
})
```

- 도메인별 Store 파일 분리 (`user.store.ts`, `auth.store.ts` 등)
- Store 내 API 호출은 허용, 단 에러 처리는 인터셉터에 위임

---

## API 호출 (Composables + Axios)

```typescript
// composables/useApi.ts — 중앙 Axios 인스턴스
const api = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL || '/api', // env.d.ts 에 타입 선언
  withCredentials: true, // HttpOnly 쿠키 전송
})

// 응답 인터셉터 — 표준 응답 언래핑 + 에러 코드 전역 처리
api.interceptors.response.use(
  (response) => response.data.data, // { success, data } → data 언래핑
  (error) => {
    const code = error.response?.data?.error?.code
    // 에러 코드별 Toast 알림 처리 (CLAUDE.md 에러 맵 참조)
    return Promise.reject(error)
  },
)
```

```typescript
// composables/useUser.ts — 도메인별 API Composable
export function useUser() {
  const loading = ref(false)
  const error = ref<string | null>(null)

  async function getUser(id: number) {
    loading.value = true
    try {
      return await api.get(`/users/${id}`)
    } finally {
      loading.value = false
    }
  }

  return { loading, error, getUser }
}
```

- API 호출 로직은 반드시 `composables/` 폴더에 분리
- 컴포넌트 내 `axios.get()` 직접 호출 **금지**

---

## 라우터 (Vue Router)

```typescript
// 코드 스플리팅 — 모든 페이지 컴포넌트는 lazy import
const routes = [
  {
    path: '/dashboard',
    component: () => import('@/pages/DashboardPage.vue'),
    meta: { requiresAuth: true },
  },
]

// 네비게이션 가드 — 인증 처리
router.beforeEach((to) => {
  const authStore = useAuthStore()
  if (to.meta.requiresAuth && !authStore.isLoggedIn) {
    return '/login'
  }
})
```

---

## 성능 & 최신 트렌드 추가 규칙

- **컴포넌트 분리**: 200줄 이상 컴포넌트는 분리 고려
- **`defineAsyncComponent`**: 무거운 컴포넌트는 비동기 로딩 적용
- **`v-memo`**: 반복 렌더링 최적화 필요 시 활용
- **`<Suspense>`**: 비동기 컴포넌트 로딩 상태 처리에 활용
- **환경변수**: 모든 설정값은 `import.meta.env.VITE_*` 형태로 관리
- **절대경로**: `@/` 경로 alias 사용 (상대경로 `../../` 지양)
- **접근성(a11y)**: `aria-label`, `role`, `tabindex` 등 기본 접근성 속성 포함