Vue 3 Composition API discipline

Contracts first

A component is an API. Before writing markup, write the contract:

// ❌ implicit contract — every prop optional, everything stringly-typed
defineProps(['item', 'dense', 'onChange'])

// ✅ explicit, typed, minimal
const props = withDefaults(defineProps<{
  item: Todo
  dense?: boolean
}>(), { dense: false })

const emit = defineEmits<{
  change: [value: Todo['id'], source: 'user' | 'sync']
}>()

Rules:

1. Props are data, not config soup. If you pass more than 5 booleans, the component is doing two jobs — split it.
2. defineEmits with tuple syntax — typed payloads prevent the "what's in $event again" archaeology.
3. v-model per field, not per form. v-model:title beats passing objects with update:* noise.

provide/inject boundaries

• provide is for framework-level context (theme, i18n, feature flags), not for skipping props.
• Injection keys must be typed and exported from one module:

// keys.ts
export const THEME_KEY: InjectionKey<Theme> = Symbol('theme')

• If two components communicate via provide/inject and neither is an ancestor factory, that's a hidden global — use a store instead.

Composables: extract behavior, not syntax

Extract a composable when you have stateful behavior (timer, subscription, undo stack), not to save lines:

// ✅ behavior: owns state + lifecycle
export function useInterval(cb: () => void, ms: MaybeRef<number>) {
  let id: ReturnType<typeof setInterval> | undefined
  watch(() => toValue(ms), (ms) => {
    if (id) clearInterval(id)
    if (ms > 0) id = setInterval(cb, ms)
  }, { immediate: true })
  onScopeDispose(() => id && clearInterval(id))
}

Anti-patterns:

• useXxx() that only wraps a computed — that's a function, keep it plain.
• Composables that call onMounted for side effects instead of watch/watchEffect — breaks SSR and testability.

Reactivity: don't lose the thread

• Destructuring props breaks reactivity — use toRefs(props) or keep props.x.
• reactive() for objects, ref() for primitives and API results. Mixing reactive arrays with replacement logic is a classic bug source; prefer ref<T[]> + value = next.
• Async state: derive with computed from a single source of truth (status + data + error), never three parallel refs you must keep in sync.

Performance without micro-optimizing

• Reach for shallowRef for large lists you replace wholesale.
• v-memo only with measured renders; it's a contract that the memo deps fully determine output — wrong deps = stale UI.
• Virtualize lists > 1k rows; don't paginate what users scroll.

Definition of done (agent checklist)

• Props/emits are typed; no defineProps(['a','b'])
• No prop drilling past 2 levels (provide or store instead)
• Every composable owns its cleanup (onScopeDispose)
• SSR-safe: no window/document outside lifecycle guards
• List rendering keyed by stable ids, never index