1---
2title: Use markRaw() for Objects That Should Never Be Reactive
3impact: MEDIUM
4impactDescription: Library instances, DOM nodes, and complex objects cause overhead and bugs when wrapped in Vue proxies
5type: efficiency
6tags: [vue3, reactivity, markRaw, performance, external-libraries, dom]
7---
8 
9# Use markRaw() for Objects That Should Never Be Reactive
10 
11**Impact: MEDIUM** - Vue's `markRaw()` tells the reactivity system to never wrap an object in a Proxy. Use it for library instances, DOM nodes, class instances with internal state, and complex objects that Vue shouldn't track. This prevents unnecessary proxy overhead and avoids subtle bugs from double-proxying.
12 
13Without `markRaw()`, placing these objects inside reactive state causes Vue to wrap them in Proxies, which can break library internals, cause identity issues, and waste memory on objects that don't need change tracking.
14 
15## Task Checklist
16 
17- [ ] Use `markRaw()` for third-party library instances (maps, charts, editors)
18- [ ] Use `markRaw()` for DOM elements stored in reactive state
19- [ ] Use `markRaw()` for class instances that manage their own state
20- [ ] Use `markRaw()` for large static data that will never change
21- [ ] Remember: markRaw only affects the root level - nested objects may still be proxied
22 
23**Incorrect:**
24```javascript
25import { reactive, ref } from 'vue'
26import mapboxgl from 'mapbox-gl'
27import * as monaco from 'monaco-editor'
28 
29// WRONG: Library instances wrapped in Proxy
30const state = reactive({
31  map: new mapboxgl.Map({ container: 'map' }),  // Proxied!
32  editor: monaco.editor.create(element, {}),    // Proxied!
33})
34 
35// Problems:
36// 1. Library's internal this references may break
37// 2. Unnecessary memory overhead
38// 3. Methods may not work correctly through proxy
39// 4. Performance degradation
40 
41// WRONG: DOM elements in reactive state
42const elements = reactive({
43  container: document.getElementById('app'),  // Proxied DOM node!
44})
45```
46 
47**Correct:**
48```javascript
49import { reactive, markRaw, shallowRef } from 'vue'
50import mapboxgl from 'mapbox-gl'
51import * as monaco from 'monaco-editor'
52 
53// CORRECT: Mark library instances as raw
54const state = reactive({
55  map: markRaw(new mapboxgl.Map({ container: 'map' })),
56  editor: markRaw(monaco.editor.create(element, {})),
57})
58 
59// CORRECT: Or use shallowRef for mutable references
60const map = shallowRef(null)
61onMounted(() => {
62  map.value = markRaw(new mapboxgl.Map({ container: 'map' }))
63})
64 
65// CORRECT: Large static data
66const geoJsonData = markRaw(await fetch('/huge-geojson.json').then(r => r.json()))
67const state = reactive({
68  mapData: geoJsonData  // Won't be proxied
69})
70```
71 
72**Class instances with internal state:**
73```javascript
74import { markRaw, reactive } from 'vue'
75 
76class WebSocketManager {
77  constructor(url) {
78    this.socket = new WebSocket(url)
79    this.listeners = new Map()
80  }
81 
82  on(event, callback) {
83    this.listeners.set(event, callback)
84  }
85}
86 
87// CORRECT: Mark class instance
88const wsManager = markRaw(new WebSocketManager('ws://example.com'))
89 
90const state = reactive({
91  connection: wsManager  // Won't be proxied
92})
93 
94// Can still use the instance normally
95state.connection.on('message', handleMessage)
96```
97 
98**Gotcha: markRaw only affects root level:**
99```javascript
100import { markRaw, reactive } from 'vue'
101 
102const rawObject = markRaw({
103  nested: { value: 1 }  // This nested object is NOT marked raw
104})
105 
106const state = reactive({
107  data: rawObject
108})
109 
110// rawObject itself won't be proxied
111// But if you access nested objects through a reactive parent:
112const container = reactive({ raw: rawObject })
113// container.raw.nested might still be proxied in some cases
114 
115// SAFER: Use shallowRef for the container
116import { shallowRef } from 'vue'
117const safeContainer = shallowRef(rawObject)
118```
119 
120**Combining with shallowRef for best results:**
121```javascript
122import { shallowRef, markRaw, onMounted, onUnmounted } from 'vue'
123 
124// Pattern: shallowRef + markRaw for external library instances
125export function useMapbox(containerId) {
126  const map = shallowRef(null)
127 
128  onMounted(() => {
129    const instance = new mapboxgl.Map({
130      container: containerId,
131      style: 'mapbox://styles/mapbox/streets-v11'
132    })
133 
134    // Mark raw to prevent any proxy wrapping
135    map.value = markRaw(instance)
136  })
137 
138  onUnmounted(() => {
139    map.value?.remove()
140  })
141 
142  return { map }
143}
144```
145 
146## Reference
147- [Vue.js markRaw() API](https://vuejs.org/api/reactivity-advanced.html#markraw)
148- [Vue.js Reducing Reactivity Overhead](https://vuejs.org/guide/best-practices/performance.html#reduce-reactivity-overhead-for-large-immutable-structures)
149- [Vue.js Reactivity in Depth](https://vuejs.org/guide/extras/reactivity-in-depth.html)
150