Vue.js Upgrade Guide

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

{
  "compilerOptions": {
    "jsx": "preserve"
  }
}

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "vue"
  }
}

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

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

count++
</script>

<script setup>
import { ref } from "vue"

const count = ref(0)

count.value++
</script>

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.

app.config.unwrapInjectedRef = false

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

<MyComponent
  @vnodeMounted="onMounted"
/>

<MyComponent
  @vue:mounted="onMounted"
/>

Vue 3.4 removes the deprecated v-is directive.

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

<tr is="vue:my-row"></tr>

Vue 3.5 removes the previously deprecated parseExpressions compiler option.

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.

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

const emit = defineEmits<{
  "update:modelValue": [value: string]
}>()
</script>

<script setup lang="ts">
const model = defineModel<string>()
</script>

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

<img
  :id="id"
  :src="src"
  :alt="alt"
/>

<img
  :id
  :src
  :alt
/>

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

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

Vue 3.5 enables Reactive Props Destructure by default. Variables destructured from defineProps() remain reactive and can use native JavaScript default-value syntax.

<script setup lang="ts">
const props = withDefaults(
  defineProps<{
    count?: number
  }>(),
  {
    count: 0
  }
)

watchEffect(() => {
  console.log(props.count)
})
</script>

<script setup lang="ts">
const {
  count = 0
} = defineProps<{
  count?: number
}>()

watchEffect(() => {
  console.log(count)
})
</script>

Vue 3.5 introduces useTemplateRef(), providing a cleaner Composition API for accessing template refs without manually declaring matching ref variables.

<script setup>
import {
  ref,
  onMounted
} from "vue"

const input = ref(null)

onMounted(() => {
  input.value.focus()
})
</script>

<template>
  <input ref="input" />
</template>

<script setup>
import {
  useTemplateRef,
  onMounted
} from "vue"

const input =
  useTemplateRef("input")

onMounted(() => {
  input.value?.focus()
})
</script>

<template>
  <input ref="input" />
</template>

Vue 3.5 introduces onWatcherCleanup(), allowing cleanup logic to be registered from inside watch and watchEffect callbacks.

import {
  watch,
  onWatcherCleanup
} from "vue"

watch(id, async (newId) => {
  const controller =
    new AbortController()

  onWatcherCleanup(() => {
    controller.abort()
  })

  await fetch(
    `/api/users/${newId}`,
    {
      signal: controller.signal
    }
  )
})

Vue 3.5 extends watcher handles with pause() and resume(), allowing watcher execution to be temporarily suspended without stopping the watcher permanently.

const {
  stop,
  pause,
  resume
} = watch(source, callback)

pause()

// watcher temporarily suspended

resume()

// watcher active again

stop()

Vue 3.5 allows the deep option on watchers to be a number, limiting how many object levels Vue traverses when tracking nested changes.

watch(
  state,
  callback,
  {
    deep: true
  }
)

watch(
  state,
  callback,
  {
    deep: 2
  }
)

Vue 3.5 allows async components to control when server-rendered markup is hydrated using built-in strategies such as idle, visibility, interaction and media-query hydration.

import {
  defineAsyncComponent,
  hydrateOnVisible
} from "vue"

const AsyncCard =
  defineAsyncComponent({
    loader: () =>
      import("./Card.vue"),

    hydrate:
      hydrateOnVisible()
  })

Vue 3.5 introduces useId() for generating application-unique IDs that remain stable across server rendering and client hydration.

<script setup>
import { useId } from "vue"

const id = useId()
</script>

<template>
  <label :for="id">
    Name
  </label>

  <input :id="id" />
</template>

Vue 3.5 adds the defer prop to Teleport, allowing its target to be resolved after other parts of the same update cycle have mounted.

<Teleport to="#target">
  <Modal />
</Teleport>

<!-- target generally needs
     to already exist -->

<Teleport
  defer
  to="#target"
>
  <Modal />
</Teleport>

<div id="target"></div>

Vue 3.5 supports directly nesting Teleport inside Transition, simplifying transition handling for teleported content.

Vue 3.5 introduces the data-allow-mismatch attribute for intentionally suppressing specific SSR hydration mismatch warnings.

<span
  data-allow-mismatch="text"
>
  {{ new Date().toLocaleString() }}
</span>

Vue 3.5 introduces app.onUnmount(), allowing plugins and application-level integrations to register cleanup callbacks that run when the application is unmounted.

const app = createApp(App)

app.onUnmount(() => {
  cleanupExternalResources()
})

app.mount("#app")

Vue 3.5 improves Vue Custom Elements with APIs and behavior for host access, shadow-root configuration, CSP nonces and other integration scenarios.

Vue 3.5 adds app.config.throwUnhandledErrorInProduction for applications that want unhandled framework errors to be thrown in production instead of only being logged.

const app = createApp(App)

app.config
  .throwUnhandledErrorInProduction =
  true

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

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.

Vue 3.5 refactors the reactivity system using version counting and doubly-linked dependency tracking, improving performance and reducing memory usage without changing expected application behavior.

Vue 3.5 improves reactive array tracking, significantly reducing overhead for large reactive arrays and common array operations.

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

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