There's so much here! Does that mean 3.0 is completely different, I'll have to learn the basics all over again, and migrating will be practically impossible?
We're glad you asked! The answer is no. We've gone to great lengths to ensure most of the API is the same and the core concepts haven't changed. It's long because we like to offer very detailed explanations and include a lot of examples. Rest assured, this is not something you have to read from top to bottom!
Possibly the biggest change is our new Composition API, which is entirely additive- the previous Options API will continue to be supported, as the Composition API is an advanced feature.
Start learning Vue 3 at Vue Mastery.
# New Features
Some of the new features to keep an eye on in Vue 3 include:
- Composition API
- Emits Component Option
@vue/runtime-coreto create custom renderers
The following consists a list of breaking changes from 2.x:
- Global Vue API is changed to use an application instance
- Global and internal APIs have been restructured to be tree-shakable
modelcomponent option and
syncmodifier are removed in favor of
- Render function API changed
- Functional components can only be created using a plain function
functionalattribute on single-file component (SFC)
functionalcomponent option are deprecated
- Async components now require
defineAsyncComponentmethod to be created
- Component data option should always be declared as a function
- Custom elements whitelisting is now performed during template compilation
isprop usage is restricted to the reserved
$scopedSlotsproperty is removed and need to be replaced with
- Attributes coercion strategy changed
- Custom directive API changed to align with component lifecycle
- Some transition classes got a rename:
- Component watch option and instance method
$watchno longer supports dot-delimited string paths, use a computed function as the parameter instead
- In Vue 2.x, application root container's
outerHTMLis 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
- $on, $off and $once instance methods
- Inline templates attributes
# Where should I start in a migration?
Start by running the migration helper (still under development) on a current project. We've carefully minified and compressed a senior Vue dev into a simple command line interface. Whenever they recognize an obsolete feature, they'll let you know, offer suggestions, and provide links to more info.
After that, browse through the table of contents for this page in the sidebar. If you see a topic you may be affected by, but the migration helper didn't catch, check it out.
If you have any tests, run them and see what still fails. If you don't have tests, just open the app in your browser and keep an eye out for warnings or errors as you navigate around.
By now, your app should be fully migrated. If you're still hungry for more though, you can read the rest of this page - or dive in to the new and improved guide from the beginning. Many parts will be skimmable, since you're already familiar with the core concepts.
# How long will it take to migrate a Vue 2.x app to 3.0?
It depends on a few factors:
The size of your app (small to medium-sized apps will probably be less than a day)
How many times you get distracted and start playing with a cool new feature. 😉 Not judging, it also happened to us while building 3.0!
Which obsolete features you're using. Most can be upgraded with find-and-replace, but others might take a few minutes. If you're not currently following best practices according to our styleguide, Vue 3.0 will also try harder to force you to. This is a good thing in the long run, but could also mean a significant (though possibly overdue) refactor.