vue-compat

Active contributors: Evan You, daiwei, edison

Purpose

vue-compat is the migration build for projects moving from Vue 2 to Vue 3. It exposes the Vue 2 Vue constructor and global API on top of the Vue 3 runtime, opt-in feature by feature. The compat code itself lives in @vue/runtime-core/src/compat/ and is gated by the __COMPAT__ build flag; this package is what flips the flag and bundles a different entry that exports a Vue-2-shaped default export.

The package is small (~210 lines, 6 files). The heavy lifting is in runtime-core/compat/.

Directory layout

packages/vue-compat/src/
├── index.ts            # full build with compiler-dom registered
├── runtime.ts          # runtime-only build
├── esm-index.ts        # ESM full build
├── esm-runtime.ts      # ESM runtime-only build
├── createCompatVue.ts  # builds the Vue-2-shaped global from runtime-core/compat
└── dev.ts

How it works

createCompatVue.ts calls runtime-core's createCompatVue() (packages/runtime-core/src/compat/global.ts) which returns a CompatVue global object with Vue 2's class-like API surface: Vue.config, Vue.component, Vue.directive, Vue.mixin, Vue.use, Vue.extend, Vue.set, Vue.delete, Vue.nextTick, Vue.compile. Each one wires through to the Vue 3 equivalents but emits deprecation warnings for behaviors that have changed.

packages/vue-compat/src/index.ts:

import { createCompatVue } from './createCompatVue'
import { compile } from '@vue/compiler-dom'
import { registerRuntimeCompiler } from '@vue/runtime-dom'

// register a compatible runtime compiler
function compileToFunction(template, options) { … }
registerRuntimeCompiler(compileToFunction)

const Vue: CompatVue = createCompatVue()
Vue.compile = compileToFunction
export default Vue

The compiler is configured for compat: dev-mode warnings about removed v-on .native modifier, v-if/v-for precedence change, deprecated filters, and so on, are reused from @vue/compiler-core/src/compat/compatConfig.ts.

Compat code in runtime-core

The substantive compat code lives at packages/runtime-core/src/compat/:

| File | What it covers | | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---- | ----------------------------- | | compatConfig.ts | The opt-in/opt-out registry: compat: 'MODE_2' | true | false and per-feature flags. | | global.ts | The Vue 2 global API on top of createApp. | | instance.ts | Vue 2 instance shape on top of the new ComponentPublicInstance. | | componentVModel.ts | Vue 2-style v-model on components (value/input instead of modelValue/update:modelValue). | | componentAsync.ts, componentFunctional.ts | Vue 2 async/functional component shapes. | | instanceEventEmitter.ts | $on/$off/$once (removed in Vue 3 proper). | | customDirective.ts | Old directive lifecycle names (bind/update/unbind). | | props.ts | Vue 2 prop merging quirks. | | data.ts | Vue 2 data merging. | | renderFn.ts, renderHelpers.ts | The Vue 2 h(tag, data, children) 3-arg signature. | | attrsFallthrough.ts | Vue 2 fallthrough behavior. |

Each branch is gated by __COMPAT__ and isCompatEnabled(feature, instance) so prod Vue 3 builds drop the entire compat surface.

When to use it

The Vue migration guide recommends vue-compat for incremental migrations — large Vue 2 apps where you can't rewrite everything at once. Each warned-about deprecation can be resolved per-component, and the compat features can be turned off globally as the codebase modernizes.

Integration points

• Depends on @vue/runtime-dom, @vue/compiler-dom, and (transitively) @vue/runtime-core and @vue/compiler-core with __COMPAT__ enabled.
• Drop-in replacement for vue in package.json: "vue": "npm:@vue/compat@…" is the standard pattern.

Entry points for modification

• New deprecation warning? Add a DeprecationTypes entry in packages/runtime-core/src/compat/compatConfig.ts, call warnDeprecation at the call site.
• Compat behavior change? The relevant file under packages/runtime-core/src/compat/. Tests live in packages/vue-compat/__tests__/.
• New global API surface? packages/runtime-core/src/compat/global.ts.