1---
2title: Use Debug Hooks to Trace Reactivity Issues
3impact: MEDIUM
4impactDescription: Debug hooks help identify which dependencies trigger re-renders and watcher executions
5type: efficiency
6tags: [vue3, reactivity, debugging, computed, watch, development]
7---
8 
9# Use Debug Hooks to Trace Reactivity Issues
10 
11**Impact: MEDIUM** - Vue provides debug hooks (`onTrack`, `onTrigger`, `renderTracked`, `renderTriggered`) that help identify exactly which reactive dependencies are being tracked and which mutations trigger re-execution. These are invaluable for debugging performance issues and unexpected re-renders.
12 
13Debug hooks only work in development mode and are stripped in production builds. Use them to understand why a computed property, watcher, or component is re-executing.
14 
15## Task Checklist
16 
17- [ ] Use `onTrack` and `onTrigger` options on computed/watch for granular debugging
18- [ ] Use `onRenderTracked` and `onRenderTriggered` lifecycle hooks for component render debugging
19- [ ] Add `debugger` statements inside hooks to pause execution and inspect state
20- [ ] Remove or comment out debug hooks before production (they're no-ops but add clutter)
21 
22> **Note:** `onTrack` and `onTrigger` are development-only hooks. They are stripped from production builds and may not fire in test environments (e.g., Vitest, Jest) depending on how Vue is bundled. If you need to verify reactivity behavior in tests, use direct assertions on reactive state changes rather than relying on these debug callbacks.
23 
24**Debugging computed properties:**
25```javascript
26import { ref, computed } from 'vue'
27 
28const count = ref(0)
29const doubled = computed(() => count.value * 2, {
30  onTrack(event) {
31    // Called when a dependency is tracked
32    // event.target = the reactive object
33    // event.key = the property being accessed
34    debugger
35    console.log('Tracking:', event)
36  },
37  onTrigger(event) {
38    // Called when a dependency mutation triggers re-computation
39    debugger
40    console.log('Triggered by:', event)
41  }
42})
43```
44 
45**Debugging watchers:**
46```javascript
47import { ref, watch, watchEffect } from 'vue'
48 
49const source = ref(0)
50 
51// With watch()
52watch(source, (newVal, oldVal) => {
53  console.log('Changed:', oldVal, '->', newVal)
54}, {
55  onTrack(e) {
56    debugger // Pause to see what's being tracked
57  },
58  onTrigger(e) {
59    debugger // Pause to see what triggered the watcher
60  }
61})
62 
63// With watchEffect()
64watchEffect(() => {
65  console.log('Source is:', source.value)
66}, {
67  onTrack(e) {
68    console.log('Tracking dependency:', e.key)
69  },
70  onTrigger(e) {
71    console.log('Triggered by:', e.key, 'mutation')
72  }
73})
74```
75 
76**Debugging component renders:**
77```vue
78<script setup>
79import { onRenderTracked, onRenderTriggered, ref } from 'vue'
80 
81const count = ref(0)
82 
83// Called for every reactive dependency accessed during render
84onRenderTracked((event) => {
85  console.log('Render tracked:', event.key, 'from', event.target)
86  debugger // Pause to inspect which dependencies are tracked
87})
88 
89// Called when a reactive dependency triggers re-render
90onRenderTriggered((event) => {
91  console.log('Render triggered by:', event.key)
92  console.log('Old value:', event.oldValue)
93  console.log('New value:', event.newValue)
94  debugger // Pause to see exactly what caused the re-render
95})
96</script>
97```
98 
99**Options API equivalent:**
100```javascript
101export default {
102  data() {
103    return { count: 0 }
104  },
105  renderTracked(event) {
106    console.log('Dependency tracked during render:', event)
107    debugger
108  },
109  renderTriggered(event) {
110    console.log('Re-render triggered by:', event)
111    debugger
112  }
113}
114```
115 
116**Debug event properties:**
117```javascript
118// The event object contains:
119{
120  effect: ReactiveEffect,  // The effect being debugged
121  target: object,          // The reactive object
122  type: 'get' | 'set' | 'add' | 'delete' | 'clear',
123  key: string | symbol,    // The property being accessed/mutated
124  oldValue: any,           // Previous value (for onTrigger)
125  newValue: any            // New value (for onTrigger)
126}
127```
128 
129## Reference
130- [Vue.js Reactivity in Depth - Debugging](https://vuejs.org/guide/extras/reactivity-in-depth.html#reactivity-debugging)
131- [Vue.js computed() API](https://vuejs.org/api/reactivity-core.html#computed)
132- [Vue.js onRenderTracked()](https://vuejs.org/api/composition-api-lifecycle.html#onrendertracked)
133