---
id: wiki-2026-0508-vue-architecture
title: Vue Architecture
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Vue 3, Composition API, Vue Reactivity]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [vue, reactivity, composition-api, frontend]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: vue3
---

# Vue Architecture

## 매 한 줄
> **"매 Proxy 기반 매 fine-grained reactivity 매 Composition API 의 의 의 component logic"**. 매 Evan You 매 2014 출시, 매 Vue 3 (2020) 매 Proxy + Composition API 의 매 큰 redesign — 매 2026 매 Vue 3.5 + Vapor Mode (compile-time, no virtual DOM) 매 stable, Nuxt 3 매 Vue 3 ecosystem 의 backbone.

## 매 핵심

### 매 Reactivity (Proxy-based)
- `ref(v)`: primitive wrapper, `.value` 매 access.
- `reactive(obj)`: deep Proxy on object.
- `computed(fn)`: lazy + cached derived.
- `watch / watchEffect`: side-effect tracking.
- 매 dependency 매 자동 collected — getter call 매 track, setter 매 trigger.

### 매 Composition API
- `<script setup>`: SFC 매 syntax sugar — `import + ref + onMounted` 매 top-level.
- `defineProps`, `defineEmits`, `defineExpose`, `defineModel` (Vue 3.4+).
- 매 logic 매 composable function (`useX`) 으로 매 추출 — React custom hook 의 매 equivalent.

### 매 응용
1. Nuxt 3 / 4: Vue 기반 meta-framework, SSR/SSG/ISR.
2. Vuetify, Element Plus, PrimeVue, Naive UI: component lib.
3. Pinia: 공식 store (Vuex 후속).
4. Vue Router 4: official routing.
5. VitePress: docs (Vue 매 dogfood).

## 💻 패턴

### `<script setup>` basics
```vue
<script setup lang="ts">
import { ref, computed, onMounted } from "vue";

const count = ref(0);
const double = computed(() => count.value * 2);
function inc() { count.value++; }

onMounted(() => console.log("mounted"));
</script>

<template>
  <button @click="inc">{{ count }} (x2 = {{ double }})</button>
</template>
```

### Composable (custom hook)
```ts
// useCounter.ts
import { ref, computed } from "vue";
export function useCounter(initial = 0) {
  const count = ref(initial);
  const double = computed(() => count.value * 2);
  function inc() { count.value++; }
  function reset() { count.value = initial; }
  return { count, double, inc, reset };
}
```

### Props + emits + v-model (Vue 3.4 defineModel)
```vue
<script setup lang="ts">
const props = defineProps<{ disabled?: boolean }>();
const model = defineModel<string>({ required: true });
const emit = defineEmits<{ submit: [value: string] }>();

function onSubmit() { emit("submit", model.value); }
</script>

<template>
  <input v-model="model" :disabled="disabled" />
  <button @click="onSubmit">Send</button>
</template>
```

### Pinia store
```ts
import { defineStore } from "pinia";

export const useCart = defineStore("cart", () => {
  const items = ref<{ id: string; qty: number }[]>([]);
  const total = computed(() => items.value.reduce((s, i) => s + i.qty, 0));
  function add(id: string) {
    const ex = items.value.find((i) => i.id === id);
    if (ex) ex.qty++; else items.value.push({ id, qty: 1 });
  }
  return { items, total, add };
});
```

### Async component + Suspense
```vue
<script setup>
import { defineAsyncComponent } from "vue";
const Heavy = defineAsyncComponent(() => import("./HeavyChart.vue"));
</script>

<template>
  <Suspense>
    <template #default><Heavy /></template>
    <template #fallback>Loading…</template>
  </Suspense>
</template>
```

### Provide / inject (typed)
```ts
// keys.ts
import type { InjectionKey, Ref } from "vue";
export const ThemeKey: InjectionKey<Ref<"light" | "dark">> = Symbol("theme");

// Parent.vue
import { provide, ref } from "vue";
const theme = ref<"light" | "dark">("dark");
provide(ThemeKey, theme);

// Child.vue
import { inject } from "vue";
const theme = inject(ThemeKey)!;
```

### Watcher patterns
```ts
import { ref, watch, watchEffect } from "vue";
const query = ref("");

watch(query, async (q, prev, onCleanup) => {
  const ctrl = new AbortController();
  onCleanup(() => ctrl.abort());
  const r = await fetch(`/api?q=${q}`, { signal: ctrl.signal });
  // …
}, { debounce: 300 } as any); // VueUse 매 watchDebounced 권장
```

### Vapor Mode (Vue 3.5+, compile-time, no VDOM)
```vue
<!-- @vue:vapor -->
<script setup lang="ts">
import { ref } from "vue";
const count = ref(0);
</script>
<template>
  <button @click="count++">{{ count }}</button>
</template>
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 신규 Vue project | Vue 3.5 + `<script setup>` + Pinia + Vite |
| SSR / SSG / hybrid | Nuxt 3/4 |
| 작은 widget / island | Vue 3 standalone + Vapor Mode |
| Vue 2 legacy | Migration build → Vue 3 점진 |
| Component lib 제작 | Vue 3 + vite library mode |

**기본값**: Vue 3.5 + Composition API + `<script setup>` + Pinia + TypeScript.

## 🔗 Graph
- 변형: [[React]] · [[Solid.js]]
- 응용: [[Pinia]]
- Adjacent: [[Composition API]]

## 🤖 LLM 활용
**언제**: Vue SFC 작성, composable 추출, Pinia store 설계, Nuxt 3 page/server route.
**언제 X**: React-only ecosystem 매 require (Next.js / RSC), native mobile (use Vue Native lacks support — RN 의 React 권장).

## ❌ 안티패턴
- **Reactive 의 destructure**: `const { x } = reactive(o)` 매 reactivity loss — `toRefs` 사용.
- **Mutating props**: 매 read-only — `defineModel` / emit.
- **Options API + Composition API 혼용**: 한 component 매 일관.
- **`watch` deep on huge object**: performance hit — narrow target.
- **Global state in `ref` module-level**: SSR 매 cross-request leak — Pinia 사용.
- **`v-html` with user input**: XSS — sanitize 또는 component 사용.

## 🧪 검증 / 중복
- Verified (Vue 3.5 official docs, Evan You ViteConf 2025 keynote, Nuxt 4 release notes).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Vue 3.5, Vapor Mode, Composition API patterns, Pinia |