Migrate to Vue 3
Prerequisites
Before starting the migration, make sure to read through the Getting Started Guide to get a broad overview of what you need to do.
1. Setting Up the Vue-Compat Build and ESLint
Not a lot of developers know, that the Vue maintainers created a compatibility build for Vue 3 (vue-compat). It all allows Vue 2 and Vue 3 code to coexist, making it possible to upgrade incrementally. Old syntax and features can be disabled globally or component wise so that you can upgrade every component one by one.
Start by installing the Vue-compat package using npm:
npm install @vue/compatNext, configure ESLint to help catch potential compatibility issues during development. This involves installing the ESLint plugin for Vue and adjusting your ESLint configuration to extend the recommended settings for Vue 3:
{ "extends": ["plugin:vue/vue3-recommended"], "plugins": ["vue"]}The Vue-compat build functions as a bridge, enabling you to use new Vue 3 features while still supporting existing Vue 2 code. That means one half of your team can still ship features while the other half does the migration.
2. Utilizing the Vue-Compat Guide
The Vue community wrote up a detailed guide on how to best use the Vue-compat build. Once your application runs successfully with the Vue-compat build, you can consider using it in a production environment while incrementally introducing Vue 3 features in new components or pages.
I recommend following the official guide as it contains all the neccessary steps to get your app running again.
3. Updating Third-Party Component Libraries
Having a third party component library can be a real headache when migrating to Vue 3. Therefore make sure to doublecheck the documentation for each library before upgrading. They often come with a migration guide that will help you get started.
If a library does not support Vue 3, you will need to either upgrade it yourself (by forking the repo and doing the neccessary changes), find an alternative that can be used as a replacement or replace it with your own components.
From my experience, it often is easiest to just recreate the components from scratch. That is especially true if those components don’t have a lot of functionality anyway.
4. Refactoring Your Own Components
With third-party libraries updated, you can focus on migrating your own components. Using the Vue-compat build, you can incrementally disable old features on a per-component basis and update accordingly. This flexibility makes it easier to refactor components gradually.
Aim to remove all Vue 2-specific features from your components to finally support Vue 3. Depending on the size of your project, you might consider batch upgrading components and globally disabling the Vue 2 compatibility flag once you feel confident in the stability of the migrated components. e.g. replacing value with modelValue with a find/replace.
5. Frequently Asked Questions (FAQ)
Can I Migrate if I Use the Vue Runtime Build with DOM Templates?
Yes, it is possible to migrate even if you are using the Vue runtime build with DOM templates. The Vue-compat build supports this setup, but you will need to refactor your templates to align with Vue 3 syntax and best practices. However, it might be time to move on to the recommended setup: Single File Components. Learn more about why you might want to avoid DOM templates.
Can I keep adding features while migrating?
Absolutely! The Vue-compat build allows you to maintain a mix of Vue 2 and Vue 3 code, so you can progressively introduce Vue 3 features in new components or parts of your application while still running existing Vue 2 code.
Need Assistance?
If you need help with your migration, feel free to contact me via email or visit the contact page. I offer professional assistance and guidance for migrations at fair rates.