1---
2title: Call toValue() Inside watchEffect for Proper Dependency Tracking
3impact: HIGH
4impactDescription: Calling toValue() outside watchEffect prevents reactive dependency tracking, causing the effect to never re-run
5type: gotcha
6tags: [vue3, composables, composition-api, watchEffect, toValue, reactivity]
7---
8 
9# Call toValue() Inside watchEffect for Proper Dependency Tracking
10 
11**Impact: HIGH** - When writing composables that accept `MaybeRefOrGetter` arguments, you must call `toValue()` inside the `watchEffect` callback, not outside. If you extract the value before the watchEffect, Vue cannot track the dependency and the effect will never re-run when the source changes.
12 
13This is a subtle but critical mistake that leads to composables that work with initial values but never update.
14 
15## Task Checklist
16 
17- [ ] Always call `toValue()` inside `watchEffect` callbacks, not before
18- [ ] Similarly, access `.value` on refs inside watchEffect, not outside
19- [ ] For `watch()`, use a getter function that calls `toValue()`
20- [ ] Test that composables update when their inputs change
21 
22**Incorrect:**
23```javascript
24import { ref, watchEffect, toValue } from 'vue'
25 
26export function useFetch(url) {
27  const data = ref(null)
28  const error = ref(null)
29 
30  // WRONG: toValue called outside watchEffect
31  // This extracts the value ONCE and passes a static string
32  const urlValue = toValue(url)
33 
34  watchEffect(async () => {
35    try {
36      // urlValue is a static string - no dependency tracked!
37      const response = await fetch(urlValue)
38      data.value = await response.json()
39    } catch (e) {
40      error.value = e
41    }
42  })
43 
44  return { data, error }
45}
46 
47// When used like this:
48const apiUrl = ref('/api/users')
49const { data } = useFetch(apiUrl)
50 
51// Later...
52apiUrl.value = '/api/products'  // useFetch will NOT refetch!
53```
54 
55**Correct:**
56```javascript
57import { ref, watchEffect, toValue } from 'vue'
58 
59export function useFetch(url) {
60  const data = ref(null)
61  const error = ref(null)
62 
63  watchEffect(async () => {
64    // CORRECT: toValue called INSIDE watchEffect
65    // Vue tracks this as a dependency
66    const urlValue = toValue(url)
67 
68    try {
69      const response = await fetch(urlValue)
70      data.value = await response.json()
71    } catch (e) {
72      error.value = e
73    }
74  })
75 
76  return { data, error }
77}
78 
79// Now when used:
80const apiUrl = ref('/api/users')
81const { data } = useFetch(apiUrl)
82 
83// Later...
84apiUrl.value = '/api/products'  // useFetch WILL refetch!
85```
86 
87## The Same Applies to Direct Ref Access
88 
89```javascript
90// WRONG: Accessing .value outside the effect
91export function useDebounce(source, delay = 300) {
92  // This captures the initial value, not a reactive dependency
93  const initialValue = source.value  // or toValue(source)
94 
95  watchEffect(() => {
96    // initialValue is static - this only runs once
97    console.log('Value:', initialValue)
98  })
99}
100 
101// CORRECT: Access inside the effect
102export function useDebounce(source, delay = 300) {
103  watchEffect(() => {
104    // Vue tracks source.value or toValue(source) as dependency
105    console.log('Value:', toValue(source))
106  })
107}
108```
109 
110## Pattern: Using watch() with Getter Functions
111 
112For `watch()`, wrap `toValue()` in a getter:
113 
114```javascript
115import { ref, watch, toValue } from 'vue'
116 
117export function useLocalStorage(key, defaultValue) {
118  const data = ref(defaultValue)
119 
120  // CORRECT: Use getter function with watch
121  watch(
122    () => toValue(key),  // Getter calls toValue, tracks dependency
123    (newKey) => {
124      const stored = localStorage.getItem(newKey)
125      data.value = stored ? JSON.parse(stored) : defaultValue
126    },
127    { immediate: true }
128  )
129 
130  return data
131}
132```
133 
134## Why This Happens
135 
136Vue's reactivity tracking works by detecting property accesses during effect execution:
137 
138```javascript
139watchEffect(() => {
140  // When this runs, Vue is "recording" what reactive sources are accessed
141  const value = someRef.value  // Vue records: "this effect depends on someRef"
142})
143 
144// But if you extract the value before:
145const value = someRef.value  // Vue isn't recording yet
146watchEffect(() => {
147  console.log(value)  // Just using a plain JavaScript variable
148})
149```
150 
151`toValue()` works the same way - it accesses `.value` internally, so it must happen during effect execution for tracking to work.
152 
153## Quick Checklist for Composable Authors
154 
155When accepting `MaybeRefOrGetter` inputs:
156 
1571. Store the raw argument (don't call `toValue` during setup)
1582. Call `toValue()` inside any reactive context (`watchEffect`, `watch`, `computed`)
1593. Test with both static values AND refs that change
160 
161```javascript
162export function useMyComposable(input) {
163  // Store raw - don't extract value here
164  // const value = toValue(input)  // WRONG
165 
166  const result = computed(() => {
167    // Extract value inside reactive context
168    return transform(toValue(input))  // CORRECT
169  })
170 
171  watchEffect(() => {
172    // Extract value inside reactive context
173    doSomething(toValue(input))  // CORRECT
174  })
175 
176  return { result }
177}
178```
179 
180## Reference
181- [Vue.js Reactivity API - toValue](https://vuejs.org/api/reactivity-utilities.html#tovalue)
182- [Vue.js Composables - Accepting Ref Arguments](https://vuejs.org/guide/reusability/composables.html#accepting-reactive-state)
183