Vue.js Upgrade Guide

Vue 3.3 repurposes the rarely used defineComponent() function overload to support improved generic component typing, changing its TypeScript type behavior.

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.1 adds onServerPrefetch(), allowing Composition API components to register asynchronous work that should be resolved during server-side rendering.

<script>
import {
  ref,
  onServerPrefetch
} from 'vue'

export default {
  setup() {
    const data = ref(null)

    onServerPrefetch(async () => {
      data.value = await fetchData()
    })

    return {
      data
    }
  }
}
</script>

Vue 3.2 stabilizes <script setup>, a compile-time syntax for using the Composition API inside Single-File Components with less boilerplate.

<script>
import { ref } from "vue"

export default {
  setup() {
    const count = ref(0)

    const increment = () => {
      count.value++
    }

    return {
      count,
      increment
    }
  }
}
</script>

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

const count = ref(0)

const increment = () => {
  count.value++
}
</script>

Vue 3.2 stabilizes the :slotted() pseudo-class for scoped SFC styles, allowing a component to explicitly style content passed through slots.

<template>
  <slot />
</template>

<style scoped>
:slotted(.message) {
  color: red;
}
</style>

Vue 3.2 introduces defineCustomElement(), allowing Vue components to be packaged and registered as native Custom Elements.

import {
  defineCustomElement
} from "vue"
import MyElement from "./MyElement.ce.vue"

const MyCustomElement =
  defineCustomElement(MyElement)

customElements.define(
  "my-element",
  MyCustomElement
)

Vue 3.2 introduces effectScope() for grouping reactive effects such as computed values and watchers so they can be disposed together.

import {
  effectScope,
  computed,
  watch
} from "vue"

const scope = effectScope()

scope.run(() => {
  const doubled = computed(
    () => state.count * 2
  )

  watch(
    () => state.count,
    () => {
      // react to changes
    }
  )
})

scope.stop()

Vue 3.2 expands server-side rendering APIs with renderToWebStream() for environments that support the Web Streams API.

import {
  renderToWebStream
} from "@vue/server-renderer"

const stream =
  renderToWebStream(app)

Vue 3.3 introduces defineOptions(), allowing additional component options such as inheritAttrs to be declared directly inside <script setup>.

<script>
export default {
  inheritAttrs: false
}
</script>

<script setup>
// component logic
</script>

<script setup>
defineOptions({
  inheritAttrs: false
})
</script>

Vue 3.3 introduces experimental support for destructuring defineProps() while preserving reactivity and allowing native default-value syntax.

Vue 3.3 introduces the experimental defineModel() compiler macro for declaring a component v-model prop and its corresponding update event with less boilerplate.

<script setup>
const props = defineProps({
  modelValue: String
})

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

<script setup>
const modelValue =
  defineModel<string>()
</script>

Vue 3.3 enhances toRef() so it can normalize values, getters and existing refs, and introduces toValue() for normalizing values, refs and getters into values.

import {
  ref,
  toRef,
  toValue
} from "vue"

const existing = ref(1)

toRef(1)
toRef(() => props.count)
toRef(existing)

toValue(1)
toValue(existing)
toValue(() => props.count)

Vue 3.3 improves getter handling in reactivity utilities, making getter-based reactive inputs easier and more efficient to consume in composables.

useFeature(
  computed(() => props.id)
)

useFeature(
  () => props.id
)

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.3 expands type support in macros such as defineProps() and defineEmits(), allowing imported types and a broader set of complex TypeScript types to be used directly.

<script setup lang="ts">
interface Props {
  name: string
  age?: number
}

defineProps<Props>()
</script>

<script setup lang="ts">
import type { UserProps } from "./types"

defineProps<UserProps>()
</script>

Vue 3.3 adds native support for declaring generic Single-File Components using the generic attribute on <script setup>.

<script
  setup
  lang="ts"
  generic="T extends string | number"
>
defineProps<{
  items: T[]
  selected: T
}>()
</script>

Vue 3.3 allows type-based defineEmits declarations to use event names as object keys and tuple types for event arguments.

const emit = defineEmits<{
  (e: "change", id: number): void
  (e: "update", value: string): void
}>()

const emit = defineEmits<{
  change: [id: number]
  update: [value: string]
}>()

Vue 3.3 introduces the defineSlots() compiler macro for providing IDE and vue-tsc type information about slot names and slot props.

<script setup lang="ts">
defineSlots<{
  default?: (
    props: { message: string }
  ) => any

  item?: (
    props: { id: number }
  ) => any
}>()
</script>

Vue 3.3 adds support for TypeScript's jsxImportSource option, allowing Vue JSX typing to be opted into explicitly and reducing conflicts with other JSX ecosystems.

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

Vue 3.3 improves TypeScript support for authoring generic components with defineComponent(), complementing generic support in <script setup>.

Vue 3.2 includes major reactivity performance improvements, reducing overhead in dependency tracking and reactive effect execution.

Vue 3.2 improves template compiler performance, reducing compilation costs for templates and Single-File Components.

Vue 3.2 includes runtime optimizations that reduce memory usage and improve performance when creating and updating component trees.

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.1 includes compiler improvements for generating and propagating source maps for Single-File Components.

Vue 3.2 improves server-side rendering support, including an ESM-bundler build of @vue/server-renderer for better integration with modern build tools.

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.

Vue 3.1 introduced the @vue/compat migration build, which provides Vue 2 compatible behavior with runtime warnings for APIs and behaviors that need to be migrated.