Vue.js Upgrade Guide

Compare Vue.js versions and see exactly what changes, what requires action, and what you can start using.

→
12Changes
5Breaking
5Actions
3Features
0Migration tools

Breaking Changes

Global JSX namespace registration was removed

Action required
breakinghigh impact

Vue 3.4 no longer registers the global JSX namespace by default, avoiding global type collisions with other JSX ecosystems such as React.

Beforevue
{
  "compilerOptions": {
    "jsx": "preserve"
  }
}
Aftervue
{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "vue"
  }
}
Migration

TSX users should set jsxImportSource to vue in tsconfig.json or add an @jsxImportSource vue pragma per file. Projects that depend on the old global JSX namespace can explicitly reference vue/jsx.

Official sources
Vue 3.4.0 Changelog — Global JSX Registration Removed ↗ Vue Documentation — JSX Type Inference ↗

Reactivity Transform was removed from Vue core

Action required
breakinghigh impact

Vue 3.4 removes the experimental Reactivity Transform feature, including compile-time macros such as $ref(), from Vue core.

Beforevue
<script setup>
let count = $ref(0)

count++
</script>
Aftervue
<script setup>
import { ref } from "vue"

const count = ref(0)

count.value++
</script>
Migration

Replace Reactivity Transform macros with standard Vue reactivity APIs, or migrate to the Vue Macros plugin if the transform syntax should be retained.

Official sources
Vue Documentation — Reactivity Transform ↗ Vue 3.4.0 Changelog ↗

app.config.unwrapInjectedRef was removed

Action required
breakinglow impact

Vue 3.4 removes app.config.unwrapInjectedRef. Injected refs are unwrapped according to the behavior that had already become the default in Vue 3.3.

Beforevue
app.config.unwrapInjectedRef = false
Migration

Remove usages of app.config.unwrapInjectedRef. Vue 3.4 no longer allows opting out of the injected-ref unwrapping behavior.

Official sources
Vue 3.4.0 Changelog ↗

Deprecated @vnodeXXX event listeners became compiler errors

Action required
breakingmedium impact

Vue 3.4 removes the deprecated @vnodeXXX template event syntax. The replacement @vue:XXX lifecycle listener syntax must be used.

Beforevue
<MyComponent
  @vnodeMounted="onMounted"
/>
Aftervue
<MyComponent
  @vue:mounted="onMounted"
/>
Migration

Replace deprecated @vnodeXXX lifecycle event listeners with the corresponding @vue:XXX syntax.

Official sources
Vue 3.4.0 Changelog ↗

Deprecated v-is directive was removed

Action required
breakingmedium impact

Vue 3.4 removes the deprecated v-is directive.

Beforevue
<tr v-is="'vue:my-row'"></tr>
Aftervue
<tr is="vue:my-row"></tr>
Migration

Replace v-is with the is attribute and the vue: prefix where Vue component resolution on native elements is required.

Official sources
Vue 3.4.0 Changelog ↗

New Features

defineModel() became stable

featurehigh impact

Vue 3.4 promotes defineModel() from experimental to stable, providing a concise way to declare a component v-model prop and its corresponding update event.

Beforevue
<script setup lang="ts">
const props = defineProps<{
  modelValue: string
}>()

const emit = defineEmits<{
  "update:modelValue": [value: string]
}>()
</script>
Aftervue
<script setup lang="ts">
const model = defineModel<string>()
</script>
Migration

No migration is required. Projects that avoided defineModel() while it was experimental can now adopt the stable API. Vue 3.4 also removes the previous local option and supports local mutation by default.

Official sources
Vue 3.4 "Slam Dunk" ↗ Vue Documentation — defineModel ↗

Same-name v-bind shorthand introduced

featurelow impact

Vue 3.4 supports a shorthand for bindings where the attribute name and JavaScript variable name are identical.

Beforevue
<img
  :id="id"
  :src="src"
  :alt="alt"
/>
Aftervue
<img
  :id
  :src
  :alt
/>
Migration

No migration is required. The shorthand can be adopted where a v-bind argument has the same name as the bound variable.

Official sources
Vue 3.4 "Slam Dunk" ↗

MathML support introduced

featurelow impact

Vue 3.4 adds built-in recognition and rendering support for MathML elements.

Aftervue
<template>
  <math>
    <mfrac>
      <mi>a</mi>
      <mi>b</mi>
    </mfrac>
  </math>
</template>
Migration

No migration is required. MathML can be used directly in Vue templates.

Official sources
Vue 3.4.0 Changelog ↗

Performance

Template parser rewritten for substantially better performance

performancemedium impact

Vue 3.4 introduces a rewritten template parser that is approximately twice as fast, improving Single-File Component and template compilation performance.

Migration

No migration is required. Applications and build tooling receive the parser performance improvements after upgrading.

Official sources
Vue 3.4 "Slam Dunk" ↗

Reactivity system became more efficient

performancehigh impact

Vue 3.4 refactors the reactivity system so computed values and effects trigger more accurately and avoid unnecessary executions in a number of common cases.

Migration

No migration is required. Existing applications benefit automatically from the more efficient reactivity implementation.

Official sources
Vue 3.4 "Slam Dunk" ↗

Tooling

SSR hydration mismatch diagnostics improved

toolingmedium impact

Vue 3.4 improves hydration mismatch checks and development diagnostics, providing clearer information about mismatched server and client output.

Migration

No migration is required. SSR applications receive more informative hydration mismatch diagnostics after upgrading.

Official sources
Vue 3.4 "Slam Dunk" ↗ Vue 3.4.0 Changelog ↗

Production hydration mismatch details can be enabled

toolinglow impact

Vue 3.4 adds the false compile-time feature flag for including detailed hydration mismatch information in production builds.

Migration

No migration is required. SSR tooling can opt into detailed production hydration mismatch diagnostics when the additional information is useful.

Official sources
Vue 3.4.0 Changelog ↗