agent-skills/skills/vue-best-practices/reference/render-function-avoid-internal-vnode-properties.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Do Not Rely on Internal VNode Properties	MEDIUM	Using undocumented vnode properties causes code to break on Vue updates	gotcha	vue3 render-function vnode internal-api

Do Not Rely on Internal VNode Properties

Impact: MEDIUM - The VNode interface contains many internal properties used by Vue's rendering system. Relying on any properties other than the documented public ones will cause your code to break when Vue's internal implementation changes.

Only use the documented vnode properties: type, props, children, and key. All other properties are internal implementation details that may change without notice between Vue versions.

Task Checklist

• Only access documented vnode properties: type, props, children, key
• Never access properties like el, component, shapeFlag, patchFlag, etc.
• If you need DOM element access, use template refs instead
• Treat vnodes as opaque data structures for rendering, not inspection

Incorrect:

import { h } from 'vue'

export default {
  setup(props, { slots }) {
    return () => {
      const slotContent = slots.default?.()

      // WRONG: Accessing internal properties
      if (slotContent?.[0]?.el) {
        // el is an internal property
        console.log(slotContent[0].el.tagName)
      }

      // WRONG: Using shapeFlag internal property
      if (slotContent?.[0]?.shapeFlag & 1) {
        // This is internal implementation
      }

      return h('div', slotContent)
    }
  }
}

// WRONG: Inspecting component instance via vnode
const vnode = h(MyComponent)
console.log(vnode.component) // Internal property
console.log(vnode.appContext) // Internal property

Correct:

import { h } from 'vue'

export default {
  setup(props, { slots }) {
    return () => {
      const slotContent = slots.default?.()

      // CORRECT: Only use documented properties
      if (slotContent?.[0]) {
        const vnode = slotContent[0]
        console.log(vnode.type)     // Safe: element type or component
        console.log(vnode.props)    // Safe: props object
        console.log(vnode.children) // Safe: children
        console.log(vnode.key)      // Safe: key prop
      }

      return h('div', slotContent)
    }
  }
}

import { h, ref, onMounted } from 'vue'

export default {
  setup() {
    // CORRECT: Use template refs for DOM access
    const divRef = ref(null)

    onMounted(() => {
      // Safe way to access DOM element
      console.log(divRef.value.tagName)
    })

    return () => h('div', { ref: divRef }, 'Content')
  }
}

Documented VNode Properties

Property	Type	Description
type	string | Component	Element tag name or component definition
props	object | null	Props passed to the vnode
children	any	Child vnodes, text, or slots
key	string | number | null	Key for list rendering

Safe VNode Inspection Patterns

import { h, isVNode } from 'vue'

export default {
  setup(props, { slots }) {
    return () => {
      const children = slots.default?.() || []

      // Safe: Check if something is a vnode
      children.forEach(child => {
        if (isVNode(child)) {
          // Safe: Check vnode type
          if (typeof child.type === 'string') {
            console.log('Element:', child.type)
          } else if (typeof child.type === 'object') {
            console.log('Component:', child.type.name)
          }

          // Safe: Read props
          if (child.props?.class) {
            console.log('Has class:', child.props.class)
          }
        }
      })

      return h('div', children)
    }
  }
}

Why This Matters

Vue's internal vnode structure may change for:

• Performance optimizations
• New feature implementations
• Bug fixes
• Tree-shaking improvements

Code relying on internal properties will break silently or throw errors when upgrading Vue versions. The documented properties are part of Vue's public API and are guaranteed to remain stable.

Reference

• Vue.js Render Function APIs
• Vue.js Render Functions - The Virtual DOM