My experience with migrating from Vue 2 to Vue 3

The migration of Vue 2 to Vue 3 is not easy. Especially if your team has a large codebase with lots of moving parts. It is important to plan and strategize your migration strategy.

Due to the major API changes, I recommend taking some precautions before starting the migration. In this article, I would like to share my experience with migrating from Vue 2 to Vue 3 in my team. These are some hard lessons that I learnt along the way. I hope after reading this article, your team is able to build a robust migration strategy.

Can I use AI to help refactor my component?

The answer is yes and no. The emergence of ChatGPT has proven to be a powerful tool in every developer's toolkit. Using ChatGPT to facilitate the migration is encouraged but it is important to know its limitations (error-prone, inaccurate, lack of knowledge etc.). Your team might choose to use another AI tool, but I have primarily used ChatGPT for my daily activities.

Using the right prompts, you might be able to achieve some level of success. However, I personally found it to me more of hindrance than an assistance. Here is sample prompt I used for small components (< 250 lines of code) in our codebase.

You are code translator, that takes a VueJs 2 component written using the Options API and converts it to a vuejs 3 using composition API. These are your guidelines:

1. Replace class-based component with the Composition API.

2. Use the <script setup> syntax for the script section.

3. Define props using defineProps.

4. Convert methods to regular functions inside eg: function doSomething() { ... };.

5. Replace this.$t and i18n.t function calls with the $t function, which you can import with const $t = inject('$translate');.

6. Preserve translation keys in the format of 'NAMESPACE.KEY'.

7. Use 4 spaces for indentation.

8. Avoid destructuring props; use props.propName.

9. Convert computed properties to use the computed function.

10. Do not return the template part under any circumstances, even as an example, I only care about the script.

But beware as ChatGPT is not a 100% accurate. My personal relationship with ChatGPT for migrating has been anything but successful. Often times, the results yield incorrect responses and I personally had not used it to assist in my migration.

I want to use the new Composition API

Assuming that your team did not use the backport of the Compostion API available in Vue 2.7+, the migration to composition API is a significant change.

In my opinion, the Composition API is a really powerful as it allows you to compose your components with composables. It is simpler to read and easier for new developers to onboard onto your project.

We decided to switch to the Composition API from the Options API which included major breaking changes. I would recommend the following when moving from the Options to Composition API:

• Use defineProps for defining your props. You will get the added benefit of defining types and other attributes for your props (eg: required)

• Use ref for tracking reactive dependencies (from data). Ensure you read the documentation for accessing the value for a ref

• Use JS functions to replace your methods

I would recommend using ChatGPT for this part. However ensure the naming, types, and data are correct. This is the only place where I would recommend using ChatGPT since the changes are small but still error-prone.

Things to consider

After successfully having migrated a medium-sized project (25+ components), I have learnt some valuable lessons along the way.

• Identify and documents any third party libraries and ensure there is Vue 3 supported version. Avoid using beta versions of any libraries as they are not stable

  • Design an action plan how how these packages will be removed/replaced

• Read the migration guide. Review the breaking changes

• Read up on your bundler and its support for Vue 3

  • We used Laramix (Laravel + Webpack) in our project. There were minor API changes but nothing that required setting up a new bundler configuration

• Enabling vue-compat can allow your app to run without crashing. It is semi-Vue 2 compatible (it will throw runtime warning for features that have been deprecated)

• Accessing refs require .value access. This is cumbersome, but careless review will often lead to your code silently failing. Review each line (I mean it).

• v-model for checkbox and radio no longer accept truthy/falsy values. Only true and false are accepted.

  • You will need to use the true-value and false-value to declare what the true and false are for the model

References/Credits

• AI prompt for Vue 3 migration

• Cover art