Back to Airi

Reactivity, Lifecycle & Composables

.agents/skills/vue/references/core-new-apis.md

0.10.15.1 KB
Original Source

Reactivity, Lifecycle & Composables

Reactivity

ref vs shallowRef

ts
import { ref, shallowRef } from 'vue'

// ref - deep reactivity (tracks nested changes)
const user = ref({ name: 'John', profile: { age: 30 } })
user.value.profile.age = 31 // Triggers reactivity

// shallowRef - only .value assignment triggers reactivity (better performance)
const data = shallowRef({ items: [] })
data.value.items.push('new') // Does NOT trigger reactivity
data.value = { items: ['new'] } // Triggers reactivity

Prefer shallowRef for large data structures or when deep reactivity is unnecessary.

computed

ts
import { computed, ref } from 'vue'

const count = ref(0)

// Read-only computed
const doubled = computed(() => count.value * 2)

// Writable computed
const plusOne = computed({
  get: () => count.value + 1,
  set: (val) => { count.value = val - 1 }
})

reactive & readonly

ts
import { reactive, readonly } from 'vue'

const state = reactive({ count: 0, nested: { value: 1 } })
state.count++ // Reactive

const readonlyState = readonly(state)
readonlyState.count++ // Warning, mutation blocked

Note: reactive() loses reactivity on destructuring. Use ref() or toRefs().

Watchers

watch

ts
import { ref, watch } from 'vue'

const count = ref(0)

// Watch single ref
watch(count, (newVal, oldVal) => {
  console.log(`Changed from ${oldVal} to ${newVal}`)
})

// Watch getter
watch(
  () => props.id,
  id => fetchData(id),
  { immediate: true }
)

// Watch multiple sources
watch([firstName, lastName], ([first, last]) => {
  fullName.value = `${first} ${last}`
})

// Deep watch with depth limit (Vue 3.5+)
watch(state, callback, { deep: 2 })

// Once (Vue 3.4+)
watch(source, callback, { once: true })

watchEffect

Runs immediately and auto-tracks dependencies.

ts
import { onWatcherCleanup, ref, watchEffect } from 'vue'

const id = ref(1)

watchEffect(async () => {
  const controller = new AbortController()

  // Cleanup on re-run or unmount (Vue 3.5+)
  onWatcherCleanup(() => controller.abort())

  const res = await fetch(`/api/${id.value}`, { signal: controller.signal })
  data.value = await res.json()
})

// Pause/resume (Vue 3.5+)
const { pause, resume, stop } = watchEffect(() => {})
pause()
resume()
stop()

Flush Timing

ts
// 'pre' (default) - before component update
// 'post' - after component update (access updated DOM)
// 'sync' - immediate, use with caution

watch(source, callback, { flush: 'post' })
watchPostEffect(() => {}) // Alias for flush: 'post'

Lifecycle Hooks

ts
import {
  onActivated, // KeepAlive
  onBeforeMount,
  onBeforeUnmount,
  onBeforeUpdate,
  onDeactivated, // KeepAlive
  onErrorCaptured,
  onMounted,
  onServerPrefetch, // SSR only
  onUnmounted,
  onUpdated
} from 'vue'

onMounted(() => {
  console.log('DOM is ready')
})

onUnmounted(() => {
  // Cleanup timers, listeners, etc.
})

// Error boundary
onErrorCaptured((err, instance, info) => {
  console.error(err)
  return false // Stop propagation
})

Effect Scope

Group reactive effects for batch disposal.

ts
import { effectScope, onScopeDispose } from 'vue'

const scope = effectScope()

scope.run(() => {
  const count = ref(0)
  const doubled = computed(() => count.value * 2)

  watch(count, () => console.log(count.value))

  // Cleanup when scope stops
  onScopeDispose(() => {
    console.log('Scope disposed')
  })
})

// Dispose all effects
scope.stop()

Composables

Composables are functions that encapsulate stateful logic using Composition API.

Naming Convention

  • Start with use: useMouse, useFetch, useCounter

Pattern

ts
// composables/useMouse.ts
import { onMounted, onUnmounted, ref } from 'vue'

export function useMouse() {
  const x = ref(0)
  const y = ref(0)

  const update = (e: MouseEvent) => {
    x.value = e.pageX
    y.value = e.pageY
  }

  onMounted(() => window.addEventListener('mousemove', update))
  onUnmounted(() => window.removeEventListener('mousemove', update))

  return { x, y }
}

Accept Reactive Input

Use toValue() (Vue 3.3+) to normalize refs, getters, or plain values.

ts
import type { MaybeRefOrGetter } from 'vue'

import { ref, toValue, watchEffect } from 'vue'

export function useFetch(url: MaybeRefOrGetter<string>) {
  const data = ref(null)
  const error = ref(null)

  watchEffect(async () => {
    data.value = null
    error.value = null

    try {
      const res = await fetch(toValue(url))
      data.value = await res.json()
    }
    catch (e) {
      error.value = e
    }
  })

  return { data, error }
}

// Usage - all work:
useFetch('/api/users')
useFetch(urlRef)
useFetch(() => `/api/users/${props.id}`)

Return Refs (Not Reactive)

Always return plain object with refs for destructuring compatibility.

ts
// Good - preserves reactivity when destructured
return { x, y }

// Bad - loses reactivity when destructured
return reactive({ x, y })
<!-- Source references: - https://vuejs.org/api/reactivity-core.html - https://vuejs.org/api/reactivity-advanced.html - https://vuejs.org/api/composition-api-lifecycle.html - https://vuejs.org/guide/reusability/composables.html -->