Vue.js Upgrade Guide

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

→
12Changes
0Breaking
0Actions
6Features
1Migration tools

New Features

onServerPrefetch added to the Composition API

featurelow impact

Vue 3.1 adds onServerPrefetch(), allowing Composition API components to register asynchronous work that should be resolved during server-side rendering.

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

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

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

    return {
      data
    }
  }
}
</script>
Migration

No migration is required. Use onServerPrefetch() when Composition API logic needs to fetch or prepare asynchronous data during server-side rendering.

Official sources
Vue 3.1.0 Release ↗

<script setup> became stable

featurehigh impact

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

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

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

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

    return {
      count,
      increment
    }
  }
}
</script>
Aftervue
<script setup>
import { ref } from "vue"

const count = ref(0)

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

No migration is required. Existing setup() components remain valid. <script setup> can be adopted incrementally to reduce Composition API boilerplate in Single-File Components.

Official sources
Vue 3.2 "Quintessential Quintuplets" ↗ Vue Documentation — <script setup> ↗

:slotted() selector became stable

featurelow impact

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

Aftervue
<template>
  <slot />
</template>

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

No migration is required. Use :slotted() when scoped component styles need to target elements provided by a parent through slots.

Official sources
Vue 3.2 "Quintessential Quintuplets" ↗ Vue Documentation — SFC CSS Features ↗

Web Components support with defineCustomElement

featuremedium impact

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

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

const MyCustomElement =
  defineCustomElement(MyElement)

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

No migration is required. Use defineCustomElement() when Vue components need to be distributed or consumed as native Web Components.

Official sources
Vue 3.2 "Quintessential Quintuplets" ↗ Vue Documentation — Vue and Web Components ↗

Effect scopes introduced

featuremedium impact

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

Aftervue
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()
Migration

No migration is required. effectScope() is primarily useful for reusable composables and libraries that need explicit control over groups of reactive effects.

Official sources
Vue 3.2 "Quintessential Quintuplets" ↗ Vue Reactivity API — effectScope ↗

Web Streams SSR API introduced

featurelow impact

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

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

const stream =
  renderToWebStream(app)
Migration

No migration is required. The streaming API can be adopted by SSR runtimes that support Web Streams.

Official sources
Vue 3.2 "Quintessential Quintuplets" ↗

Performance

Reactivity performance improved

performancemedium impact

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

Migration

No migration is required. Existing applications receive the reactivity performance improvements after upgrading.

Official sources
Vue 3.2 "Quintessential Quintuplets" ↗

Template compiler performance improved

performancelow impact

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

Migration

No migration is required. Applications and build tooling benefit automatically after upgrading.

Official sources
Vue 3.2 "Quintessential Quintuplets" ↗

Runtime memory usage reduced

performancelow impact

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

Migration

No migration is required. The runtime optimizations apply automatically after upgrading.

Official sources
Vue 3.2 "Quintessential Quintuplets" ↗

Tooling

SFC compiler source map support improved

toolinglow impact

Vue 3.1 includes compiler improvements for generating and propagating source maps for Single-File Components.

Migration

No migration is required. Tooling built on @vue/compiler-sfc can benefit from the improved source map support.

Official sources
Vue 3.1.0 Release ↗

SSR package became ESM-bundler compatible

toolinglow impact

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

Migration

No migration is required for most applications. SSR tooling and frameworks can use the improved server-renderer packaging with modern ESM-based build pipelines.

Official sources
Vue 3.2 "Quintessential Quintuplets" ↗

Migration Tools

Migration Build for Vue 2 applications

migrationmedium impact

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.

Migration

Projects migrating from Vue 2 can temporarily alias vue to @vue/compat and use compatibility warnings to migrate incrementally. The compatibility build is intended as a migration aid and should be removed after migration is complete.

Official sources
Vue 3 Migration Build ↗ Vue 3.1.0 Release ↗