2nd/10_Wiki/Topics/Frontend/Composables.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-composables	Composables (Vue)	10_Wiki/Topics	verified	self	Vue Composables useX functions	none	A	0.9	applied	vue composition-api composables frontend		2026-05-10	pending	language framework TypeScript Vue 3

Composables (Vue)

매 한 줄

"매 reactive logic 의 reusable function". Composable 은 Vue 3 Composition API 의 stateful logic 을 추출한 useX() 함수 — React Hooks 와 유사하나 매 reactivity primitive (ref, reactive, computed) 기반이라 caller 매 free of dependency arrays.

매 핵심

매 정의

• use* prefix 매 convention.
• Returns reactive refs / computed / methods.
• Side-effects via onMounted / onScopeDispose (watchEffect cleanup).
• effectScope 매 manual lifecycle (e.g., outside components).

매 vs React Hooks

Aspect	Vue Composable	React Hook
Re-run	매 once on setup	every render
Deps	reactive auto-track	manual array
Cleanup	onScopeDispose	return fn
Conditional call	허용 (with caveats)	금지

매 응용

1. useFetch / useAsyncData — async + cancellation.
2. useElementSize, useEventListener — DOM bindings (VueUse).
3. useStore, useFeatureFlag — cross-cutting state.

💻 패턴

Basic counter composable

import { ref, computed } from 'vue';

export function useCounter(initial = 0) {
  const count = ref(initial);
  const isZero = computed(() => count.value === 0);
  const inc = () => count.value++;
  const dec = () => count.value--;
  return { count, isZero, inc, dec };
}

useFetch with abort + reactive URL

import { ref, watchEffect, onScopeDispose, type MaybeRefOrGetter, toValue } from 'vue';

export function useFetch<T>(url: MaybeRefOrGetter<string>) {
  const data = ref<T | null>(null);
  const error = ref<Error | null>(null);
  const loading = ref(false);
  let ctrl: AbortController | null = null;

  watchEffect(async () => {
    ctrl?.abort();
    ctrl = new AbortController();
    loading.value = true;
    try {
      const r = await fetch(toValue(url), { signal: ctrl.signal });
      data.value = await r.json();
    } catch (e) {
      if ((e as Error).name !== 'AbortError') error.value = e as Error;
    } finally {
      loading.value = false;
    }
  });

  onScopeDispose(() => ctrl?.abort());
  return { data, error, loading };
}

useEventListener (auto cleanup)

import { onMounted, onScopeDispose, type Ref } from 'vue';

export function useEventListener<K extends keyof WindowEventMap>(
  target: Window | Ref<HTMLElement | null>,
  event: K,
  handler: (e: WindowEventMap[K]) => void,
) {
  onMounted(() => {
    const el = 'value' in target ? target.value : target;
    el?.addEventListener(event, handler as EventListener);
  });
  onScopeDispose(() => {
    const el = 'value' in target ? target.value : target;
    el?.removeEventListener(event, handler as EventListener);
  });
}

useLocalStorage (sync ref ↔ storage)

import { ref, watch } from 'vue';

export function useLocalStorage<T>(key: string, initial: T) {
  const stored = localStorage.getItem(key);
  const value = ref<T>(stored ? JSON.parse(stored) : initial);
  watch(value, (v) => localStorage.setItem(key, JSON.stringify(v)), { deep: true });
  return value;
}

useDebouncedRef

import { customRef } from 'vue';

export function useDebouncedRef<T>(value: T, delay = 300) {
  let t: ReturnType<typeof setTimeout>;
  return customRef<T>((track, trigger) => ({
    get() { track(); return value; },
    set(v) {
      clearTimeout(t);
      t = setTimeout(() => { value = v; trigger(); }, delay);
    },
  }));
}

Detached scope (composable outside component)

import { effectScope } from 'vue';

const scope = effectScope();
scope.run(() => {
  const counter = useCounter();
  // ... use anywhere
});
// later
scope.stop();

매 결정 기준

상황	Approach
Component-local state	ref directly
Logic reused in 2+ components	Composable
Global state (auth, theme)	Pinia store (composable underneath)
DOM API integration	VueUse composable or custom

기본값: 매 reusable reactive logic → composable. Single-use → inline.

🔗 Graph

• 부모: Composition API · Vue 3
• 변형: React-Hooks · Solid-Primitives
• 응용: VueUse · Pinia · Nuxt-Composables
• Adjacent: Reactivity · Component-Composition

🤖 LLM 활용

언제: stateful logic 매 2+ components 에서 사용 / DOM·async 의 lifecycle wrapping. 언제 X: 매 pure function (no reactivity) — 매 plain util 로 충분.

❌ 안티패턴

• Returning reactive() with destructure: loses reactivity → use toRefs.
• Global side-effects in composable body: 매 onMounted 안에 넣을 것.
• Naming without use prefix: 매 convention break, lint rule 매 fail.

🧪 검증 / 중복

• Verified (Vue.js docs / VueUse source).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — Vue 3 composables with patterns