Extension mechanism of custom renderers

Custom Renderer Extension Mechanism

Vue 3's renderer design adopts a highly abstract pattern, with core logic being platform-agnostic. This design allows developers to extend Vue's capabilities through custom renderers, enabling it to operate in non-DOM environments such as Canvas, WebGL, or even native applications.

Renderer Core Architecture

Vue 3's renderer consists of two parts:

1. Renderer Core: Handles the creation, updating, and destruction of the virtual DOM.
2. Platform-Specific APIs: Handles actual rendering operations.

interface RendererOptions<Node, Element> {
  patchProp: (
    el: Element,
    key: string,
    prevValue: any,
    nextValue: any
  ) => void
  insert: (child: Node, parent: Element, anchor?: Node | null) => void
  remove: (child: Node) => void
  createElement: (tag: string) => Element
  createText: (text: string) => Node
  // ...Other platform-specific methods
}

Creating a Custom Renderer

A custom renderer can be created using the createRenderer function, which accepts an object containing platform-specific implementations:

import { createRenderer } from 'vue'

const { render, createApp } = createRenderer({
  patchProp(el, key, prevValue, nextValue) {
    // Custom attribute handling logic
  },
  insert(child, parent, anchor) {
    // Custom insertion logic
  },
  createElement(tag) {
    // Custom element creation logic
    return new CanvasElement(tag)
  },
  // Other required methods...
})

Practical Example: Canvas Renderer

Below is a simplified implementation of a Canvas renderer:

const { createApp } = createRenderer({
  createElement(tag) {
    return {
      tag,
      type: 'element',
      children: [],
      style: {},
      attributes: {}
    }
  },
  insert(child, parent) {
    if (parent.children) {
      parent.children.push(child)
    }
  },
  patchProp(el, key, prevVal, nextVal) {
    if (key.startsWith('on')) {
      // Handle events
      const eventType = key.slice(2).toLowerCase()
      el[`on${eventType}`] = nextVal
    } else {
      // Handle attributes and styles
      el.attributes[key] = nextVal
    }
  },
  createText(text) {
    return { type: 'text', text }
  },
  setElementText(node, text) {
    node.text = text
  }
})

function renderToCanvas(app, canvas) {
  const ctx = canvas.getContext('2d')
  // Implement specific Canvas rendering logic
  // ...
}

const app = createApp(App)
renderToCanvas(app, document.getElementById('canvas'))

Node Operation Extensions

A custom renderer needs to implement a complete node operation interface:

interface NodeOperations<Node, Element> {
  createElement: (tag: string) => Element
  createText: (text: string) => Node
  setText: (node: Node, text: string) => void
  insert: (child: Node, parent: Element, anchor?: Node | null) => void
  remove: (child: Node) => void
  parentNode: (node: Node) => Element | null
  nextSibling: (node: Node) => Node | null
  querySelector?: (selector: string) => Element | null
}

Lifecycle Hook Integration

Custom renderers can extend component lifecycles:

const { createApp } = createRenderer({
  // ...Other methods
  onBeforeMount() {
    console.log('Canvas element is about to be created')
  },
  onMounted() {
    console.log('Canvas element has been created')
  },
  onBeforeUpdate() {
    console.log('Canvas element is about to update')
  },
  onUpdated() {
    console.log('Canvas element has been updated')
  }
})

Server-Side Rendering Support

Custom renderers can also implement server-side rendering:

const { renderToString } = createRenderer({
  // Server-specific implementations
  createElement(tag) {
    return { tag }
  },
  insert(child, parent) {
    // No actual insertion needed on the server
  },
  patchProp() {
    // Server-side attribute handling
  }
})

const html = await renderToString(createApp(App))

Performance Optimization Techniques

Implement efficient updates in custom renderers:

const { createApp } = createRenderer({
  // ...Other methods
  patchProp(el, key, prevVal, nextVal) {
    if (prevVal === nextVal) return
    // Actual update logic
  },
  shouldSetAsProps(el, key, value) {
    // Decide whether to set the value as a DOM property
    return key !== 'innerHTML'
  }
})

Integration with Vue Ecosystem

Custom renderers can maintain compatibility with the Vue ecosystem:

const { createApp } = createRenderer({
  // ...Basic implementation
})

const app = createApp(App)
app.use(VueRouter)  // Can still use VueRouter
app.use(Pinia)      // Can still use state management

Handling Complex Scenarios

Dealing with component boundaries and complex scenarios like Portals:

const { createApp } = createRenderer({
  // ...Basic methods
  resolveContainer(container) {
    // Handle Portal target containers
    if (typeof container === 'string') {
      return document.querySelector(container)
    }
    return container
  },
  createComponentInstance(vnode) {
    // Custom component instance creation logic
  }
})

Debugging Support

Add debugging capabilities to custom renderers:

const { createApp } = createRenderer({
  // ...Basic methods
  onError(err) {
    console.error('Rendering error:', err)
  },
  warn(message) {
    console.warn('Rendering warning:', message)
  }
})

Cross-Platform Component Development

Writing components that support both DOM and Canvas:

const Circle = {
  props: ['radius', 'color'],
  setup(props) {
    // Use renderer-injected APIs
    const { drawCircle } = useRenderer()
    
    onMounted(() => {
      drawCircle(props.radius, props.color)
    })
    
    onUpdated(() => {
      drawCircle(props.radius, props.color)
    })
    
    return () => null  // Return no DOM nodes
  }
}

Deep Customization of Renderer APIs

API extensions for advanced customization scenarios:

interface ExtendedRendererOptions<Node, Element> extends RendererOptions<Node, Element> {
  // Extend custom APIs
  createCustomElement: (type: string) => Element
  applySpecialStyle: (el: Element, style: object) => void
}

const { createApp } = createRenderer<ExtendedRendererOptions>({
  // Implement extended APIs
  createCustomElement(type) {
    // Special element creation logic
  },
  applySpecialStyle(el, style) {
    // Special style handling
  }
})