Understanding Vue.js mergeOptions: How Merge Strategies Work

Yuan Dong, a front‑end engineer at WeDoctor, shares an in‑depth analysis of Vue.js's option merging mechanism.

Definition of Merge Strategies

After standardizing props, inject, directives, and the

extends

/

mixins

options, the core of

mergeOptions

is the definition of merge strategies.

The final part of the

mergeOptions

source code is:

const options = {}
let key
for (key in parent) {
  mergeField(key)
}
for (key in child) {
  if (!hasOwn(parent, key)) {
    mergeField(key)
  }
}
function mergeField (key) {
  const strat = strats[key] || defaultStrat
  options[key] = strat(parent[key], child[key], vm, key)
}

Both

parent

and

child

objects are iterated, and for each key the

mergeField()

function is called.

mergeField()

selects a strategy from

strats[key]

or falls back to

defaultStrat

and applies it.

defaultStrat

/**
 * Default strategy.
 */
const defaultStrat = function (parentVal, childVal) {
  return childVal === undefined
    ? parentVal
    : childVal
}

The logic of

defaultStrat

is simple: if the child provides a value, use it; otherwise fall back to the parent value, giving priority to the child.

strats[key]

const strats = config.optionMergeStrategies
export type Config = {
  // user
  optionMergeStrategies: { [key: string]: Function };
  ...
}

Developers can define custom merge functions for specific keys in

config.optionMergeStrategies

.

config.optionMergeStrategies.el, config.optionMergeStrategies.propsData

if (process.env.NODE_ENV !== 'production') {
  strats.el = strats.propsData = function (parent, child, vm, key) {
    if (!vm) {
      warn(`option "${key}" can only be used during instance creation with the `new` keyword.`)
    }
    return defaultStrat(parent, child)
  }
}

Both

el

and

propsData

use the default strategy: the child value wins if present, otherwise the parent value is used.

config.optionMergeStrategies.data, config.optionMergeStrategies.provide

strats.data = function (parentVal, childVal, vm) {
  if (!vm) {
    if (childVal && typeof childVal !== 'function') {
      process.env.NODE_ENV !== 'production' && warn('The "data" option should be a function that returns a per‑instance value in component definitions.', vm)
      return parentVal
    }
    return mergeDataOrFn(parentVal, childVal)
  }
  return mergeDataOrFn(parentVal, childVal, vm)
}
strats.provide = mergeDataOrFn

The

data

and

provide

strategies delegate to

mergeDataOrFn

, handling both constructor‑level and instance‑level merges.

If no

vm

(i.e., the component is created via

Vue.extend()

), the function checks whether

childVal

is a function and merges accordingly.

If a

vm

instance exists (i.e., created with

new Vue()

), the instance data is merged with the constructor data.

export function mergeDataOrFn (parentVal, childVal, vm) {
  if (!vm) {
    // Vue.extend merge: both should be functions
    if (!childVal) {
      return parentVal
    }
    if (!parentVal) {
      return childVal
    }
    return function mergedDataFn () {
      return mergeData(
        typeof childVal === 'function' ? childVal.call(this, this) : childVal,
        typeof parentVal === 'function' ? parentVal.call(this, this) : parentVal
      )
    }
  } else {
    return function mergedInstanceDataFn () {
      const instanceData = typeof childVal === 'function'
        ? childVal.call(vm, vm)
        : childVal
      const defaultData = typeof parentVal === 'function'
        ? parentVal.call(vm, vm)
        : parentVal
      if (instanceData) {
        return mergeData(instanceData, defaultData)
      } else {
        return defaultData
      }
    }
  }
}

The helper

mergeData

recursively merges two data objects, skipping the internal

__ob__

marker.

function mergeData (to, from) {
  if (!from) return to
  let key, toVal, fromVal
  const keys = hasSymbol
    ? Reflect.ownKeys(from)
    : Object.keys(from)
  for (let i = 0; i < keys.length; i++) {
    key = keys[i]
    // in case the object is already observed...
    if (key === '__ob__') continue
    toVal = to[key]
    fromVal = from[key]
    if (!hasOwn(to, key)) {
      set(to, key, fromVal)
    } else if (
      toVal !== fromVal &&
      isPlainObject(toVal) &&
      isPlainObject(fromVal)
    ) {
      mergeData(toVal, fromVal)
    }
  }
  return to
}

Hook Merging Strategy

export const LIFECYCLE_HOOKS = [
  'beforeCreate',
  'created',
  'beforeMount',
  'mounted',
  'beforeUpdate',
  'updated',
  'beforeDestroy',
  'destroyed',
  'activated',
  'deactivated',
  'errorCaptured',
  'serverPrefetch'
]
function mergeHook (parentVal, childVal) {
  const res = childVal
    ? parentVal
      ? parentVal.concat(childVal)
      : Array.isArray(childVal)
        ? childVal
        : [childVal]
    : parentVal
  return res ? dedupeHooks(res) : res
}
function dedupeHooks (hooks) {
  const res = []
  for (let i = 0; i < hooks.length; i++) {
    if (res.indexOf(hooks[i]) === -1) {
      res.push(hooks[i])
    }
  }
  return res
}
LIFECYCLE_HOOKS.forEach(hook => {
  strats[hook] = mergeHook
})

Each lifecycle hook is merged as an array; duplicate functions are removed by

dedupeHooks

.

Assets (components, directives, filters) Merging Strategy

function mergeAssets (parentVal, childVal, vm, key) {
  const res = Object.create(parentVal || null)
  if (childVal) {
    process.env.NODE_ENV !== 'production' && assertObjectType(key, childVal, vm)
    return extend(res, childVal)
  } else {
    return res
  }
}
export const ASSET_TYPES = [
  'component',
  'directive',
  'filter'
]
ASSET_TYPES.forEach(type => {
  strats[type + 's'] = mergeAssets
})

If the child defines these assets, they are merged with the parent; otherwise the parent assets are returned unchanged.

props / methods / inject / computed Merging Strategy

strats.props =
strats.methods =
strats.inject =
strats.computed = function (parentVal, childVal, vm, key) {
  if (childVal && process.env.NODE_ENV !== 'production') {
    assertObjectType(key, childVal, vm)
  }
  if (!parentVal) return childVal
  const ret = Object.create(null)
  extend(ret, parentVal)
  if (childVal) extend(ret, childVal)
  return ret
}

The strategy creates a new object, copies the parent options, then merges the child options if present.

watch Merging Strategy

strats.watch = function (parentVal, childVal, vm, key) {
  if (parentVal === nativeWatch) parentVal = undefined
  if (childVal === nativeWatch) childVal = undefined
  if (!childVal) return Object.create(parentVal || null)
  if (process.env.NODE_ENV !== 'production') {
    assertObjectType(key, childVal, vm)
  }
  if (!parentVal) return childVal
  const ret = {}
  extend(ret, parentVal)
  for (const key in childVal) {
    let parent = ret[key]
    const child = childVal[key]
    if (parent && !Array.isArray(parent)) {
      parent = [parent]
    }
    ret[key] = parent ? parent.concat(child) : Array.isArray(child) ? child : [child]
  }
  return ret
}

Watchers are merged as arrays, ensuring that multiple handlers for the same key are combined.

Conclusion

The three‑part series thoroughly dissects Vue.js's option merging process, covering data, hooks, assets, props, methods, inject, computed, and watch. Understanding these strategies helps developers customize component behavior and debug complex inheritance scenarios.