2nd/10_Wiki/Topics/Frontend/Composition API.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-composition-api	Composition API (Vue 3)	10_Wiki/Topics	verified	self	Vue Composition API setup script	none	A	0.9	applied	vue composition-api reactivity frontend		2026-05-10	pending	language framework TypeScript Vue 3

Composition API (Vue 3)

매 한 줄

"매 reactive primitive 으로 logic 을 조합한다". Composition API 는 Vue 3 의 setup() / <script setup> 기반 model — ref, reactive, computed, watch 를 직접 import 하여 매 logic 조각을 자유 조합, 매 Options API 의 data/methods/computed partition 을 대체.

매 핵심

매 핵심 primitives

• ref(v): 매 wraps any value, .value access.
• reactive(obj): deep proxy — object/array 만.
• computed(fn): derived ref, lazy + cached.
• watch(src, cb): explicit deps + cb.
• watchEffect(fn): auto-track, eager.
• effectScope(): manual lifecycle group.

매 vs Options API

Aspect	Options	Composition
Logic reuse	mixins (collision-prone)	composables (clean)
TypeScript	OK	excellent
File length scaling	grows by category	grows by feature
Learning curve	gentle	steeper but worth it

매 <script setup> perks

• Top-level await.
• Auto-expose for template.
• defineProps, defineEmits, defineModel, defineExpose macros.
• Compile-time optimizations (no setup() boilerplate).

💻 패턴

Basic setup with ref + computed

<script setup lang="ts">
import { ref, computed } from 'vue';

const count = ref(0);
const double = computed(() => count.value * 2);
const inc = () => count.value++;
</script>

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

Typed props + emits + v-model

<script setup lang="ts">
const props = defineProps<{ initial?: number }>();
const emit = defineEmits<{ change: [value: number] }>();
const model = defineModel<string>({ default: '' });
</script>

<template>
  <input v-model="model" />
</template>

reactive with toRefs (avoid losing reactivity)

import { reactive, toRefs } from 'vue';

export function useUser() {
  const state = reactive({ name: 'Ada', age: 36 });
  return { ...toRefs(state) }; // 매 destructurable + reactive
}

watch with explicit source

import { ref, watch } from 'vue';

const query = ref('');
watch(query, async (q, _old, onCleanup) => {
  const ctrl = new AbortController();
  onCleanup(() => ctrl.abort());
  const r = await fetch(`/search?q=${q}`, { signal: ctrl.signal });
  // ...
});

watchEffect (auto-track)

import { ref, watchEffect } from 'vue';

const userId = ref(1);
watchEffect(async () => {
  const r = await fetch(`/api/users/${userId.value}`);
  user.value = await r.json();
});

Provide / inject (typed)

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

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

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

Async setup with Suspense

<!-- Parent -->
<Suspense>
  <UserProfile :id="42" />
  <template #fallback><Skeleton /></template>
</Suspense>

<!-- UserProfile.vue -->
<script setup lang="ts">
const props = defineProps<{ id: number }>();
const user = await (await fetch(`/users/${props.id}`)).json();
</script>

Lifecycle hooks

import { onMounted, onUnmounted } from 'vue';

onMounted(() => console.log('mounted'));
onUnmounted(() => console.log('cleanup'));

매 결정 기준

상황	Approach
New Vue 3 project	Composition + <script setup>
Migrating from Vue 2	Options 유지 → 점진 conversion
Logic reuse needed	Composable function
Simple 1-off component	Either OK, prefer setup for TS

기본값: <script setup> + Composition API. Options API 는 legacy maintenance only.

🔗 Graph

• 부모: Vue 3
• 변형: Vue Options API · Solid-Signals
• 응용: Composables · Pinia · Nuxt
• Adjacent: Component-Composition · TypeScript

🤖 LLM 활용

언제: Vue 3 component 작성, composable 추출, TS 강한 typing 필요. 언제 X: Vue 2.7 이전 — 매 backport limited.

❌ 안티패턴

• Mixing reactive() destructure without toRefs: loses reactivity silently.
• Using ref.value in template: 매 unwrap 자동, .value 의 X.
• Excessive watch: 매 computed 로 충분한 경우 매 prefer computed.

🧪 검증 / 중복

• Verified (vuejs.org official guide).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — Composition API primitives + setup patterns