[Vue.js 3.0] Migration – Introduction

# Introduction

This guide is primarily for users with prior Vue 2 experience who want to learn about the new features and changes in Vue 3. This is not something you have to read from top to bottom before trying out Vue 3. While it looks like a lot has changed, a lot of what you know and love about Vue is still the same; but we wanted to be as thorough as possible and provide detailed explanations and examples for every documented change.

• Quickstart
• Notable New Features
• Breaking Changes
• Supporting Libraries

# Overview

Start learning Vue 3 at Vue Mastery(opens new window).

# Quickstart

• Via CDN: <script src="https://unpkg.com/vue@next"></script>

• In-browser playground on Codepen(opens new window)

• In-browser Sandbox on CodeSandbox(opens new window)

• Scaffold via Vite(opens new window):

  npm init @vitejs/app hello-vue3 # OR yarn create @vitejs/app hello-vue3
  

• Scaffold via vue-cli(opens new window):

  npm install -g @vue/cli # OR yarn global add @vue/cli
  vue create hello-vue3
  # select vue 3 preset
  

# Notable New Features

Some of the new features to keep an eye on in Vue 3 include:

• Composition API
• Teleport
• Fragments
• Emits Component Option
• createRenderer API from @vue/runtime-core(opens new window) to create custom renderers
• SFC Composition API Syntax Sugar (<script setup>)(opens new window) experimental
• SFC State-driven CSS Variables (<style vars>)(opens new window) experimental
• SFC <style scoped> can now include global rules or rules that target only slotted content(opens new window)

# Breaking Changes

The following consists a list of breaking changes from 2.x:

# Global API

• Global Vue API is changed to use an application instance
• Global and internal APIs have been restructured to be tree-shakable

# Template Directives

• v-model usage on components has been reworked, replacing v-bind.sync
• key usage on <template v-for> and non-v-for nodes has changed
• v-if and v-for precedence when used on the same element has changed
• v-bind="object" is now order-sensitive
• v-on:event.native modifier has been removed
• ref inside v-for no longer register an array of refs

# Components

• Functional components can only be created using a plain function
• functional attribute on single-file component (SFC) <template> and functional component option are deprecated
• Async components now require defineAsyncComponent method to be created
• Component events should now be declared with the emits option

# Render Function

• Render function API changed
• $scopedSlots property is removed and all slots are exposed via $slots as functions
• $listeners has been removed / merged into $attrs
• $attrs now includes class and style attributes

# Custom Elements

• Custom elements whitelisting is now performed during template compilation
• Special is prop usage is restricted to the reserved <component> tag only

# Other Minor Changes

• The destroyed lifecycle option has been renamed to unmounted
• The beforeDestroy lifecycle option has been renamed to beforeUnmount
• Props default factory function no longer has access to this context
• Custom directive API changed to align with component lifecycle
• The data option should always be declared as a function
• The data option from mixins is now merged shallowly
• Attributes coercion strategy changed
• Some transition classes got a rename
• <TransitionGroup> now renders no wrapper element by default
• When watching an array, the callback will only trigger when the array is replaced. If you need to trigger on mutation, the deep option must be specified.
• <template> tags with no special directives (v-if/else-if/else, v-for, or v-slot) are now treated as plain elements and will result in a native <template> element instead of rendering its inner content.
• In Vue 2.x, application root container's outerHTML is replaced with root component template (or eventually compiled to a template, if root component has no template/render option). Vue 3.x now uses application container's innerHTML instead - this means the container itself is no longer considered part of the template.

# Removed APIs

• keyCode support as v-on modifiers
• $on, $off and $once instance methods
• Filters
• Inline templates attributes
• $children instance property
• $destroy instance method. Users should no longer manually manage the lifecycle of individual Vue components.

# Supporting Libraries

All of our official libraries and tools now support Vue 3, but most of them are still in beta status and distributed under the next dist tag on npm. We are planning to stabilize and switch all projects to use the latest dist tag by end of 2020.

# Vue CLI

As of v4.5.0, vue-cli now provides the built-in option to choose Vue 3 when creating a new project. You can upgrade vue-cli and run vue create to create a Vue 3 project today.

• Documentation(opens new window)
• GitHub(opens new window)

# Vue Router

Vue Router 4.0 provides Vue 3 support and has a number of breaking changes of its own. Check out its migration guide(opens new window) for full details.

• Documentation(opens new window)
• GitHub(opens new window)
• RFCs(opens new window)

# Vuex

Vuex 4.0 provides Vue 3 support with largely the same API as 3.x. The only breaking change is how the plugin is installed(opens new window).

• Documentation(opens new window)
• GitHub(opens new window)

# Devtools Extension

We are working on a new version of the Devtools with a new UI and refactored internals to support multiple Vue versions. The new version is currently in beta and only supports Vue 3 (for now). Vuex and Router integration is also work in progress.

• For Chrome: Install from Chrome web store(opens new window)

  • Note: the beta channel may conflict with the stable version of devtools so you may need to temporarily disable the stable version for the beta channel to work properly.

• For Firefox: Download the signed extension(opens new window) (.xpi file under Assets)

# IDE Support

It is recommended to use VSCode(opens new window) with our official extension Vetur(opens new window), which provides comprehensive IDE support for Vue 3.

# Other Projects