Introduction
How to work with this guide
Why this guide?
Vue 3.0.0 has been released on September 18th, 2020, and naturally, people want to migrate their apps. While the official Documentation offers a pretty complete Migration guide, this only contains changes related to Vue core itself.
State of the ecosystem
But Vue projects are usually comprised of multiple core libraries besides vue itself (as well as many 3rd party lib, provided by the active community, of course), and those
other libraries are still catching up to Vue 3. Most of them are already in beta or rc stage, but the state of documentation (especially migration docs) is anywhere from "done" to "will be done soon".
Furthermore, there's no guide that shows how to approach upgrading all of these individual building blocks in a real project, so developers have to collect all of this scattered information, review it and then try and come up with a plan about how to migrate their projects.
State of the Migration tooling
None of this is to blame the Vue team - the author of this guide is part of it, after all, and knows the awesome work being done by that team. Rather, the project's official recommendation for migrating existing projects is to wait for the migration build and tooling that's being worked on for Q4/2020.
- The migration build will provide compatibility with Vue 2 APIs that changed in Vue 3 where possible (Example:
beforeDestroyed()=>beforeUnmount()lifecycle hook) and log deprecation warning. - A Migration helper CLI tool will allow you to scan your project, highlighting parts that need upgrading
- A package of codemods will allow you to have these changes done automatically for you where possible.
Taking into account that most of the Vue 2 community libraries will require an update to be compatible with Vue 3, it makes sense to wait for these tools to be provided, as by that time, many of the dependencies of existing projects will hopefully have caught up to Vue 3 as well.
Who is this guide for?
This guide is for developers who have taken into account the aforementioned state of affairs, and still want to migrate a project to Vue 3.
Maybe you have a small side project with little dependencies that you want to migrate as an exercise before you do the same for the big project at the office. Maybe you are just interested in the amount of work a migration would involve (keeping in mind that the mentioned codemods can significantly minimize the work left for the developer).
If that sounds like you, this guide is for you.
This guide also assumes that you are working on a bigger project that uses some kind of bundler, i.e. webpack (possibly in a Vue CLI setup) and make use of Vue's Single File Components format (.vue files). If you are using Vue in some other context, a lot of the migration strategies still apply, but you might have to do some transfer work in order to apply them to your situation.
How to use this guide
The foundation of this guide a small example app that contains a few components which are designed in away that they use all of the features and APIs that we will have to migrate in a typical project. We will take a look at this App a bit further down this page.
The guide itself is laid out as a guided tour through the codebase of this example app and aims to give you an idea about how to approach a migration. It answers the following questions by leading you step by step through the process of a typical migration.
Consequently, it will work best for you if you follow it from start to finish - but feel free to jump to a specific topic that's nagging you right now, if you feel the need.
We will be working our way through the app from big, important things that break your app, down to the small things that may "only" affect some visuals, and sprinkle some tips on top along the way.