1---
2name: core-new-apis
3description: Vue 3 reactivity system, lifecycle hooks, and composable patterns
4---
5 
6# Reactivity, Lifecycle & Composables
7 
8## Reactivity
9 
10### ref vs shallowRef
11 
12```ts
13import { ref, shallowRef } from 'vue'
14 
15// ref - deep reactivity (tracks nested changes)
16const user = ref({ name: 'John', profile: { age: 30 } })
17user.value.profile.age = 31  // Triggers reactivity
18 
19// shallowRef - only .value assignment triggers reactivity (better performance)
20const data = shallowRef({ items: [] })
21data.value.items.push('new')  // Does NOT trigger reactivity
22data.value = { items: ['new'] }  // Triggers reactivity
23```
24 
25**Prefer `shallowRef`** for large data structures or when deep reactivity is unnecessary.
26 
27### computed
28 
29```ts
30import { ref, computed } from 'vue'
31 
32const count = ref(0)
33 
34// Read-only computed
35const doubled = computed(() => count.value * 2)
36 
37// Writable computed
38const plusOne = computed({
39  get: () => count.value + 1,
40  set: (val) => { count.value = val - 1 }
41})
42```
43 
44### reactive & readonly
45 
46```ts
47import { reactive, readonly } from 'vue'
48 
49const state = reactive({ count: 0, nested: { value: 1 } })
50state.count++  // Reactive
51 
52const readonlyState = readonly(state)
53readonlyState.count++  // Warning, mutation blocked
54```
55 
56Note: `reactive()` loses reactivity on destructuring. Use `ref()` or `toRefs()`.
57 
58## Watchers
59 
60### watch
61 
62```ts
63import { ref, watch } from 'vue'
64 
65const count = ref(0)
66 
67// Watch single ref
68watch(count, (newVal, oldVal) => {
69  console.log(`Changed from ${oldVal} to ${newVal}`)
70})
71 
72// Watch getter
73watch(
74  () => props.id,
75  (id) => fetchData(id),
76  { immediate: true }
77)
78 
79// Watch multiple sources
80watch([firstName, lastName], ([first, last]) => {
81  fullName.value = `${first} ${last}`
82})
83 
84// Deep watch with depth limit (Vue 3.5+)
85watch(state, callback, { deep: 2 })
86 
87// Once (Vue 3.4+)
88watch(source, callback, { once: true })
89```
90 
91### watchEffect
92 
93Runs immediately and auto-tracks dependencies.
94 
95```ts
96import { ref, watchEffect, onWatcherCleanup } from 'vue'
97 
98const id = ref(1)
99 
100watchEffect(async () => {
101  const controller = new AbortController()
102  
103  // Cleanup on re-run or unmount (Vue 3.5+)
104  onWatcherCleanup(() => controller.abort())
105  
106  const res = await fetch(`/api/${id.value}`, { signal: controller.signal })
107  data.value = await res.json()
108})
109 
110// Pause/resume (Vue 3.5+)
111const { pause, resume, stop } = watchEffect(() => {})
112pause()
113resume()
114stop()
115```
116 
117### Flush Timing
118 
119```ts
120// 'pre' (default) - before component update
121// 'post' - after component update (access updated DOM)
122// 'sync' - immediate, use with caution
123 
124watch(source, callback, { flush: 'post' })
125watchPostEffect(() => {})  // Alias for flush: 'post'
126```
127 
128## Lifecycle Hooks
129 
130```ts
131import {
132  onBeforeMount,
133  onMounted,
134  onBeforeUpdate,
135  onUpdated,
136  onBeforeUnmount,
137  onUnmounted,
138  onErrorCaptured,
139  onActivated,      // KeepAlive
140  onDeactivated,    // KeepAlive
141  onServerPrefetch  // SSR only
142} from 'vue'
143 
144onMounted(() => {
145  console.log('DOM is ready')
146})
147 
148onUnmounted(() => {
149  // Cleanup timers, listeners, etc.
150})
151 
152// Error boundary
153onErrorCaptured((err, instance, info) => {
154  console.error(err)
155  return false  // Stop propagation
156})
157```
158 
159## Effect Scope
160 
161Group reactive effects for batch disposal.
162 
163```ts
164import { effectScope, onScopeDispose } from 'vue'
165 
166const scope = effectScope()
167 
168scope.run(() => {
169  const count = ref(0)
170  const doubled = computed(() => count.value * 2)
171  
172  watch(count, () => console.log(count.value))
173  
174  // Cleanup when scope stops
175  onScopeDispose(() => {
176    console.log('Scope disposed')
177  })
178})
179 
180// Dispose all effects
181scope.stop()
182```
183 
184## Composables
185 
186Composables are functions that encapsulate stateful logic using Composition API.
187 
188### Naming Convention
189 
190- Start with `use`: `useMouse`, `useFetch`, `useCounter`
191 
192### Pattern
193 
194```ts
195// composables/useMouse.ts
196import { ref, onMounted, onUnmounted } from 'vue'
197 
198export function useMouse() {
199  const x = ref(0)
200  const y = ref(0)
201 
202  const update = (e: MouseEvent) => {
203    x.value = e.pageX
204    y.value = e.pageY
205  }
206 
207  onMounted(() => window.addEventListener('mousemove', update))
208  onUnmounted(() => window.removeEventListener('mousemove', update))
209 
210  return { x, y }
211}
212```
213 
214### Accept Reactive Input
215 
216Use `toValue()` (Vue 3.3+) to normalize refs, getters, or plain values.
217 
218```ts
219import { ref, watchEffect, toValue, type MaybeRefOrGetter } from 'vue'
220 
221export function useFetch(url: MaybeRefOrGetter<string>) {
222  const data = ref(null)
223  const error = ref(null)
224 
225  watchEffect(async () => {
226    data.value = null
227    error.value = null
228    
229    try {
230      const res = await fetch(toValue(url))
231      data.value = await res.json()
232    } catch (e) {
233      error.value = e
234    }
235  })
236 
237  return { data, error }
238}
239 
240// Usage - all work:
241useFetch('/api/users')
242useFetch(urlRef)
243useFetch(() => `/api/users/${props.id}`)
244```
245 
246### Return Refs (Not Reactive)
247 
248Always return plain object with refs for destructuring compatibility.
249 
250```ts
251// Good - preserves reactivity when destructured
252return { x, y }
253 
254// Bad - loses reactivity when destructured
255return reactive({ x, y })
256```
257 
258<!--
259Source references:
260- https://vuejs.org/api/reactivity-core.html
261- https://vuejs.org/api/reactivity-advanced.html
262- https://vuejs.org/api/composition-api-lifecycle.html
263- https://vuejs.org/guide/reusability/composables.html
264-->
265