Vue 3 Composition API skill for Codex

Done well means: components use <script setup lang="ts">, state has one obvious owner, derived values are computed (never synced with a watcher), every side effect cleans up, and composables take MaybeRefOrGetter inputs so callers can pass plain values, refs or getters without losing reactivity.

Before changing code

1. Read AGENTS.md, package.json (Vue version; 3.5+ adds reactive props destructure, useTemplateRef, useId, onWatcherCleanup) and the lint config (eslint-plugin-vue rules often enforce macro order or ban reactive).
2. Look in src/composables/ (or composables/ in Nuxt) before writing a new composable. Check whether VueUse is installed; it already has useEventListener, useDebounceFn, useLocalStorage and many more.
3. Check for Nuxt: if nuxt.config.ts exists, auto-imports apply and data fetching rules differ (hand off to $nuxt-4).

Component shape

<script setup lang="ts">
import { computed, ref, watch, useTemplateRef, onMounted } from "vue";
import type { Product } from "@/types";

const { product, maxQty = 10 } = defineProps<{ product: Product; maxQty?: number }>();
const qty = defineModel<number>("qty", { required: true });
const emit = defineEmits<{ addToCart: [id: string, qty: number] }>();
defineSlots<{ default?(): any; badge?(props: { onSale: boolean }): any }>();

const input = useTemplateRef<HTMLInputElement>("qtyInput");
const total = computed(() => product.price * qty.value);
const canAdd = computed(() => qty.value > 0 && qty.value <= maxQty);

watch(() => product.id, () => { qty.value = 1; });
onMounted(() => input.value?.focus());
</script>

<template>
  <slot name="badge" :on-sale="product.onSale" />
  <input ref="qtyInput" v-model.number="qty" type="number" min="1" :max="maxQty" />
  <p>{{ total.toFixed(2) }}</p>
  <button :disabled="!canAdd" @click="emit('addToCart', product.id, qty)">Add</button>
</template>

Order inside <script setup>: imports, props, model, emits, slots, injected deps, state, computed, watchers, lifecycle hooks, functions. Keep it consistent with the repo.

Decisions

Situation	Use	Not
Primitive or value you replace wholesale	ref	reactive (cannot reassign)
Large immutable payload (API list, chart data)	shallowRef, replace .value	deep ref (proxies every node)
Group of fields always used together	ref({...}) or reactive	Destructuring a reactive (loses reactivity)
Value derived from other state	computed	watch that writes another ref
Derived value you sometimes override locally	writable computed with get/set, or ref + watch on the source	Mutating a prop
Side effect on specific sources	watch(source, cb)	watchEffect with hidden dependencies
Side effect on whatever it reads, run immediately	watchEffect
Two-way binding with parent	defineModel	prop + update: emit by hand
DOM access	useTemplateRef("name") (3.5+)	ref named like the template ref (older pattern)
Deep tree dependency injection	provide/inject with an InjectionKey<T>	Prop drilling past 3 levels; global store for local state
Cross-page shared state	Pinia ($pinia-state)	Module-level ref in SSR apps (leaks between requests)

Composables

// composables/useSearch.ts
import { ref, shallowRef, watch, toValue, onWatcherCleanup, type MaybeRefOrGetter } from "vue";

export function useSearch<T>(query: MaybeRefOrGetter<string>, fetcher: (q: string, s: AbortSignal) => Promise<T[]>) {
  const results = shallowRef<T[]>([]); // replaced wholesale, no deep proxy
  const error = ref<unknown>(null);
  const loading = ref(false);

  watch(
    () => toValue(query),
    async (q) => {
      if (!q) { results.value = []; return; }
      const ctrl = new AbortController();
      onWatcherCleanup(() => ctrl.abort()); // cancels the previous request on change
      loading.value = true;
      error.value = null;
      try {
        results.value = await fetcher(q, ctrl.signal);
      } catch (e) {
        if (!ctrl.signal.aborted) error.value = e;
      } finally {
        if (!ctrl.signal.aborted) loading.value = false;
      }
    },
    { immediate: true },
  );

  return { results, error, loading };
}

Rules for composables:

• Name useX, return an object of refs (not a reactive), so callers can destructure.
• Accept MaybeRefOrGetter and read with toValue() inside a watcher or computed.
• Call only synchronously inside setup (or another composable). After an await, lifecycle hooks and inject no longer know the current instance.
• Register cleanup: onScopeDispose for listeners and timers (works in components and in effectScope), onWatcherCleanup for per-run cleanup.
• No module-level mutable state unless the composable is deliberately a singleton and the app is client-only.

Reactivity traps

• Destructuring reactive() or a store breaks the link. Use toRefs(state) or storeToRefs(store).
• Destructuring props is reactive only in <script setup> on 3.5+ when done directly in the defineProps statement. Passing the destructured variable into watch(foo, ...) passes a plain value; write watch(() => foo, ...).
• watch(someReactive.count, ...) watches a number. Use a getter: watch(() => state.count, ...).
• watch on a reactive object is deep implicitly; on a ref of an object it is not. Use { deep: true } or deep: 1 (3.5) deliberately; deep watching large trees is slow.
• Array index assignment and Map/Set mutations are reactive in Vue 3; replacing a shallowRef’s inner object without reassigning .value is not. Call triggerRef or reassign.
• Refs auto-unwrap in templates and inside reactive objects, but not inside arrays or Maps held in reactive (list[0].value is still needed).
• Async setup (top-level await in <script setup>) makes the component require <Suspense> up the tree; prefer loading inside a composable with a loading ref.
• v-if and v-for on the same element: v-if runs first in Vue 3 and cannot see the loop variable. Use a <template v-for> wrapper or a computed filtered list.
• Use key on v-for items with a stable id, never the index for editable lists.

Converting Options API

Map one block at a time and keep behaviour identical:

Options API	Composition API
data()	ref / reactive
computed: {}	computed()
watch: {}	watch(); immediate, deep carry over
methods	plain functions
props, emits	defineProps, defineEmits (type-based)
mounted, beforeUnmount	onMounted, onBeforeUnmount
this.$refs.x	useTemplateRef("x")
this.$emit("update:modelValue")	defineModel()
mixins	composables (explicit inputs and returns, no name clashes)
this.$nextTick	await nextTick()

Write or keep a component test before converting; it must pass unchanged afterwards.

Verification

npx vue-tsc --noEmit          # type-check SFCs, including props and emits
npx eslint . --ext .ts,.vue   # if the repo uses eslint-plugin-vue
npx vitest run                # component tests with @vue/test-utils

• For a composable, test it in isolation by calling it inside a tiny host component (mount(defineComponent({ setup() { return useSearch(q, fake) } }))) and assert that changing q aborts the previous request.
• In Vue DevTools, confirm no component re-renders on unrelated state changes and that listeners disappear after unmount (Performance panel, event listener count).

Output

Report the components or composables changed, any public prop, emit or model changes (breaking for parents), and reactivity fixes with the before and after behaviour.