agents-inc/web-framework-vue-composition-api

Vue 3 Composition API

Quick Guide: Use <script setup> for all components. ref() for primitives, reactive() for objects. Extract reusable logic into composables (use* functions). Clean up side effects in onUnmounted. Use defineModel() for v-model (3.4+), useTemplateRef() for DOM refs (3.5+), onWatcherCleanup() to cancel stale async work (3.5+). Destructured props require getter wrappers in watch().

---

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use <script setup> syntax for all new Vue components)

(You MUST clean up all side effects (timers, listeners, subscriptions) in onUnmounted)

(You MUST use ref() for primitives and reactive() for objects - access ref values via .value)

(You MUST prefix all composable functions with use following Vue conventions)

(You MUST wrap destructured props in a getter for watch() - watch(() => count, ...) not watch(count, ...))

</critical_requirements>

---

Auto-detection: Vue 3 Composition API, script setup, ref, reactive, computed, watch, watchEffect, composables, onMounted, onUnmounted, defineProps, defineEmits, defineExpose, defineModel, useTemplateRef, useId, onWatcherCleanup, provide, inject, Suspense

When to use:

• Building Vue 3 components using Composition API
• Creating reusable composables (use* functions)
• Managing reactive state with ref/reactive
• Handling component lifecycle and side effects
• TypeScript integration with Vue components

Key patterns covered:

• Script setup syntax and compiler macros (defineProps, defineEmits, defineExpose)
• Reactivity primitives (ref, reactive, computed, watch, watchEffect)
• Composables pattern for logic reuse
• defineModel() for v-model binding (Vue 3.4+)
• useTemplateRef(), useId(), onWatcherCleanup() (Vue 3.5+)
• Reactive props destructure with getter requirement (Vue 3.5+)
• Provide/Inject for dependency injection
• Async components and Suspense

When NOT to use:

• Components that don't benefit from logic extraction
• When team has no Composition API experience (consider gradual adoption)

---

<philosophy>

Philosophy

The Composition API enables organizing code by logical concern rather than by option type (data, methods, computed). This makes complex components more maintainable and enables powerful logic reuse through composables.

Core principles:

1. Composition over configuration - Group related logic together instead of splitting across options
2. Explicit reactivity - State is explicitly reactive via ref() and reactive()
3. Logic reuse via composables - Extract and share stateful logic between components
4. TypeScript-first - Types flow naturally without excessive annotations

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Script Setup with Props and Emits

All variables/functions in <script setup> are automatically available in the template. Use TypeScript generics with defineProps and defineEmits for type-safe interfaces.

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

const props = defineProps<{
  userId: string;
  initialCount?: number;
}>();

const emit = defineEmits<{
  update: [value: number];
  submit: [];
}>();

const count = ref(props.initialCount ?? 0);
const doubleCount = computed(() => count.value * 2);

function increment() {
  count.value++;
  emit("update", count.value);
}
</script>

Why good: No explicit return needed, TypeScript types flow naturally, named tuple emit syntax (Vue 3.3+) self-documents payloads

See examples/core.md for a complete component with loading/error handling.

---

Pattern 2: Reactivity - ref vs reactive

ref() for primitives and reassignable values, reactive() for objects with nested properties. Access ref values via .value in script; templates unwrap automatically.

const count = ref(0); // Primitive -> ref
count.value++; // .value in script

const state = reactive({
  // Nested object -> reactive
  user: null as User | null,
  settings: { theme: "light" },
});
state.settings.theme = "dark"; // Direct access, no .value

Gotcha: Destructuring reactive() loses reactivity - use toRefs(state) if you need to destructure.

See examples/reactivity.md for ref/reactive/computed patterns and anti-patterns.

---

Pattern 3: Watch and WatchEffect

Skip if using Nuxt — use useFetch or useAsyncData instead.

watch() for explicit sources with access to old values. watchEffect() for automatic dependency tracking that runs immediately. Use onWatcherCleanup() (Vue 3.5+) to cancel stale async work.

// watch: explicit source, access to old value
watch(searchQuery, async (newQuery, oldQuery) => {
  /* ... */
});

// watchEffect: auto-tracks dependencies, runs immediately
watchEffect(async () => {
  if (userId.value) userData.value = await fetchUser(userId.value);
});

// Cleanup: cancel stale requests (Vue 3.5+)
watch(searchQuery, async (query) => {
  const controller = new AbortController();
  onWatcherCleanup(() => controller.abort());
  const res = await fetch(`/api/search?q=${query}`, {
    signal: controller.signal,
  });
});

Gotcha: Watch reactive object properties with a getter: watch(() => state.count, ...) not watch(state.count, ...).

See examples/vue-3-5-features.md for complete onWatcherCleanup patterns.

---

Pattern 4: Lifecycle and Cleanup

Always pair onMounted setup with onUnmounted cleanup. Timers, listeners, observers, WebSockets - anything opened must be closed.

const POLL_INTERVAL_MS = 5000;
let intervalId: ReturnType<typeof setInterval> | null = null;

onMounted(() => {
  intervalId = setInterval(fetchData, POLL_INTERVAL_MS);
});

onUnmounted(() => {
  if (intervalId) {
    clearInterval(intervalId);
    intervalId = null;
  }
});

See examples/lifecycle.md for WebSocket reconnection and event listener cleanup patterns.

---

Pattern 5: Composables

Extract reusable stateful logic into use* functions. Return objects with refs (not bare values) so destructuring preserves reactivity.

export function useCounter(options: UseCounterOptions = {}) {
  const { initialValue = 0, min = -Infinity, max = Infinity } = options;
  const count = ref(initialValue);
  const isAtMax = computed(() => count.value >= max);

  function increment() {
    if (count.value < max) count.value++;
  }
  function reset() {
    count.value = initialValue;
  }

  return { count, isAtMax, increment, reset }; // Return object with refs
}

Async composables should accept MaybeRefOrGetter<T> inputs (use toValue() to normalize) and return { data, error, isLoading } refs.

See examples/composables.md for useFetch, useLocalStorage, useDebounce, and useIntersectionObserver implementations.

---

Pattern 6: defineModel for v-model (Vue 3.4+)

Replaces the defineProps + defineEmits boilerplate for two-way binding. Returns a ref-like value that syncs with the parent.

<script setup lang="ts">
const model = defineModel<string>(); // Single v-model
const firstName = defineModel<string>("firstName"); // Named v-model
const [model, modifiers] = defineModel<string>({
  // With modifiers
  set(value) {
    return modifiers.capitalize
      ? value.charAt(0).toUpperCase() + value.slice(1)
      : value;
  },
});
</script>

See examples/vue-3-5-features.md for complete defineModel examples with named models and modifiers.

---

Pattern 7: Template Refs (Vue 3.5+)

useTemplateRef() separates template refs from reactive refs. Use for dynamic ref names and in composables. Traditional ref() still works for simple static refs.

<script setup lang="ts">
const inputRef = useTemplateRef<HTMLInputElement>("myInput");
onMounted(() => inputRef.value?.focus());
</script>
<template>
  <input ref="myInput" type="text" />
</template>

For child component refs: Use defineExpose() to declare the public API, then ref<InstanceType<typeof Child>>() in the parent.

See examples/define-expose.md for form validation with exposed methods and examples/vue-3-5-features.md for useTemplateRef in composables.

---

Pattern 8: useId for Accessible IDs (Vue 3.5+)

Generates SSR-safe unique IDs for form labels and ARIA attributes. Each call produces a different ID. Must be called in setup (not in computed).

<script setup lang="ts">
const id = useId();
</script>
<template>
  <label :for="id">Email</label>
  <input :id="id" type="email" />
</template>

See examples/vue-3-5-features.md for multi-field forms and ARIA patterns.

---

Pattern 9: Reactive Props Destructure (Vue 3.5+)

Destructured props are automatically reactive. Use JavaScript default syntax instead of withDefaults(). The critical gotcha: destructured props require a getter wrapper in watch().

<script setup lang="ts">
const {
  title,
  count = 0,
  items = () => [],
} = defineProps<{
  title: string;
  count?: number;
  items?: string[];
}>();

// CORRECT: getter wrapper
watch(
  () => count,
  (newCount) => {
    /* ... */
  },
);

// WRONG: passes value, not reactive source
// watch(count, ...) // Never triggers!
</script>

See examples/vue-3-5-features.md for complete reactive destructure examples.

---

Pattern 10: Provide/Inject

Type-safe dependency injection to avoid prop drilling. Define InjectionKey<T> symbols in a separate file, provide in ancestor, inject in descendant with an explicit error for missing providers.

// injection-keys.ts
export const THEME_KEY: InjectionKey<ThemeContext> = Symbol("theme");

// Provider: provide(THEME_KEY, { theme, toggleTheme });
// Consumer: const ctx = inject(THEME_KEY);
//           if (!ctx) throw new Error("Must be used within ThemeProvider");

See examples/provide-inject.md for a complete theme provider/consumer pattern.

---

Pattern 11: Async Components and Suspense

defineAsyncComponent for code-splitting. Top-level await in <script setup> makes a component async (requires <Suspense> in parent). Use onErrorCaptured at the Suspense boundary for error handling.

const LOADING_DELAY_MS = 200;
const LOAD_TIMEOUT_MS = 10000;

const HeavyChart = defineAsyncComponent({
  loader: () => import("@/components/HeavyChart.vue"),
  loadingComponent: LoadingSpinner,
  delay: LOADING_DELAY_MS,
  timeout: LOAD_TIMEOUT_MS,
});

See examples/async.md for Suspense boundaries with error handling.

</patterns>

---

Detailed Resources:

• examples/core.md - Complete component, template refs, focus management
• examples/reactivity.md - ref, reactive, computed patterns and anti-patterns
• examples/composables.md - useFetch, useLocalStorage, useDebounce, useIntersectionObserver
• examples/lifecycle.md - WebSocket, timers, event listeners, cleanup patterns
• examples/provide-inject.md - Theme provider, typed injection keys
• examples/define-expose.md - Form field validation, parent-child coordination
• examples/vue-3-5-features.md - defineModel, useTemplateRef, useId, onWatcherCleanup, reactive destructure, deferred Teleport
• examples/async.md - Lazy loading, Suspense, async setup
• reference.md - Decision frameworks, TypeScript patterns, anti-patterns, checklists

---

<red_flags>

RED FLAGS

High Priority Issues:

• Missing cleanup in onUnmounted - timers, listeners, subscriptions, WebSockets cause memory leaks
• Accessing ref.value in template - templates auto-unwrap refs, writing .value in templates is wrong
• Destructuring reactive() without toRefs() - loses reactivity silently
• Watching destructured prop directly - watch(count, ...) never triggers, use watch(() => count, ...)

Medium Priority Issues:

• Watch without async cleanup - causes race conditions; use onWatcherCleanup() (3.5+) or the cleanup callback
• Using provide() with string keys instead of typed InjectionKey<T> symbols - loses type safety
• Returning bare values from composables instead of an object with refs - breaks destructuring reactivity

Gotchas & Edge Cases:

• Refs in reactive objects are auto-unwrapped at root level, but NOT in arrays or Map/Set
• watchEffect runs immediately; watch is lazy by default
• Computed values are read-only by default; use getter/setter object for writable computed
• Top-level await makes a component async and requires <Suspense> in parent
• Provide values are not reactive by default - wrap in ref() or reactive() if consumers need reactivity
• onUnmounted won't run if component errors during setup - use error boundaries for critical cleanup
• useId() must not be called in computed - it generates a new ID each call
• defineModel returns a ref - use .value in script, auto-unwrapped in template

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST use <script setup> syntax for all new Vue components)

(You MUST clean up all side effects (timers, listeners, subscriptions) in onUnmounted)

(You MUST use ref() for primitives and reactive() for objects - access ref values via .value)

(You MUST prefix all composable functions with use following Vue conventions)

(You MUST wrap destructured props in a getter for watch() - watch(() => count, ...) not watch(count, ...))

Failure to follow these rules will cause memory leaks, broken reactivity, and unmaintainable component APIs.

</critical_reminders>