Migrate Vue 2 to Vue 3

My first advice is to keep your current app as up-to-date as possible. Especially when your Vue version is below 2.7.x, I would recommend you to update it. With Vue 2.7.x "Naruto" release, the Vue team aimed to backport lots of features from Vue 3 to Vue 2 without introducing a breaking change. This will help you to migrate some things in preparation for a smooth Vue 3 switch. Check out the official announcement and start migrating to the Vue 3 flavour in your Vue 2 app:

Are you using TypeScript right now or do you plan to migrate to TypeScript? In that case you should read the TypeScript Notes for Vue 3. Generally I would highly recommend to use TypeScript as the Vue 2 and Vue 3 TypeScript integration is great. It will help you a lot to reduce runtime errors as hard debugging nights by analyzing bugs in production. Be prepared, that switching to Typescript might require quite an effort, but it’s still worth it.

A big thing you definitely have to check before is: dependencies. You should check if you are using packages that will rely on Vue 2 and won’t be available for Vue 3. Such dependencies will require your attention as they may block you from updating to Vue 3. In my previous project we weren’t able to update to Vue 3 a long time since we had a dependency to BootstrapVue which wasn’t working with Vue 3 and isn’t still. In such case where a package isn’t compatible you have the following options:

In all these cases you should make yourself a list of the relevant development tasks with a very rough estimate about how complex the migration will be. For example write a + if the dependency migration is straight forward (already Vue 3 compatible). Write + for very hard-to-migrate dependencies, where you may need another solution or lib or implement stuff by yourself. Add Notes about things you shouldn’t forget when starting the migration. You should also include development dependencies for example for webpack plugins. It could look like the following example:

For dependency update / migrations you can’t estimate, it’s a good idea to set them up / try them out in an isolated new Vue 3 playground environment. After playing around, you should be able to estimate the effort. A good example when having a look at the migration list above would be to try out the rollup-plugin-license package.

When coming from webpack and planning to migrate to Vite, you should check your webpack config for any special behaviors. You can use the playground to reflect / try out the setup in Vite. Here are some points that were interesting for us:

When currently using Vuex, you may be lucky, and you have already some modules splitting your store into logical parts. In our case we had just one big store without any modules as the codebase has evolved over time, and we haven’t made the step to split the store. The migration to Pinia can be a good chance to face this now as Pinia lets you easily compose multiple small stores. You should check your current store configuration and write down the modules that are loosely coupled or even completely independent (e.g. a user or an auth store).

The last thing we have done was to create a new epic for the whole migration and to create small estimable tasks. This was very important as we were now able to identify things we can prepare and do even before we started the migration itself and also tasks we can do in advance. On the other hand it helped us for the communication with the product owner and to make things transparent. Please keep in mind to add some time buffer for unexpected things occurring during the migration where you may need some extra time. For example: the migration from Vuex to Pinia took a lot more time than we thought before. But: it was definitely worth it. The TypeScript support is way better and the unification of actions and mutations reduces the Boilerplate code a lot. We also underestimated the time we needed to migrate the tests. This was hard by definition but quite time-consuming as I wrote in the introduction: We had a huge Vuex store.

Vue 3 kicked out the concept of using filters in the template using the pipe (|) syntax ({{ expression | myFilter }}). Filters are simply functions that can be imported and used directly. You can already import the functions, use them as a method and then pass through the expression in the template before starting the Vu3 migration: {{ myFilter(expression) }}.

Update all possible dependencies to their latest versions to make migrations for other libs in advance. At this step: double-check if vue-specific libs are ready for using with Vue 3 or if there are other libs you have to use. If you have to change to other libs and this one supports Vue 3, make the migration now. In our team we had already lots of our dependencies updated, since we are using Mend (formerly Whitesource) Renovate for housekeeping and continuous dependency version updates.

When you decide to migrate a dependency to a new one that supports Vue 2 and Vue 3 or which should be replaced with a self-implementation: Do it in advance before the actual Vue migration.

It may happens, you realize, for some of your dependencies a migration won’t be straight-forward. In our case we decided some years ago, we want to use Leaflet.js as our map library to display and interact with features on a map. Therefore we also used a wrapper for Vue 2 applications called Vue2Leaflet which made us use Leaflet in a declarative manner. However, this architectural decision was now a problem for us, as not only this dependency is not supposed to use it with Vue 3 but also extensions for this library such as Leaflet.heat needed to be migrated. To face this issue we’ve gone one step back and rethink our architectural decision to use Leaflet. At this time there was already a Vue 3 wrapper for leaflet available but not as feature-rich as we needed it. So we created a new Architectural Decision Record (ADR) to evaluate and choose our future map library as it is a central component of our app and can’t be easily replaced. After doing a Proof-of-Concept (PoC), we decided to switch to OpenLayers and make use of the vue3-openlayers wrapper too, where we were also able to contribute missing features back into the project.

This whole story is probably quite special to my team and our app, but the essential thing here was, that we prepared the central components in parallel to our productive app in a separate repository in isolation. Therefore, we created the components and defined their props and events with the help of Storybook. Of course, we also created tests for these components, so that we were prepared to copy over all this into the productive app and replace the existing components later, when we were ready to actually migrate to Vue 3.

A drawback with this approach is of course: It probably blocks you with releasing new features or you have to implement them twice during the preparation time (one time for the productive app based on Vue 2, one time for the isolated components based on Vue 3).

When checking your Vue 3 default setup you will notice that some NPM script names have changed by default. For example the default command to run the development build and server is now npm run dev instead of npm run serve. You can either change the names back since you are used to the "old" commands, or you can already name your commands in the Vue 2 setup to the new ones to get comfy with it. Please note that you may have to change the commands in you CI/CD Pipeline too.

You can switch to Vite before updating to Vue 3 this makes the "big bang" migration a bit smaller. For that, you should install Vite and use the official plugin @vitejs/plugin-vue2. You also need to migrate all the webpack plugins and configs. When the setup is finished, cleanup all the webpack stuff including the config and the dependencies.

During the migration we noticed, that we haven’t used Type-Only Imports in all our typescript and .vue files. The default Vite setup is configured in such way, Type-Only Imports will be forced when needed, otherwise you’ll receive errors during the build. We had the option to either deactivate this strict behavior by setting the typescript config option importsNotUsedAsValues to either preserve or remove (not recommended) or to migrate. Luckily, there is a community project called ts-import-types-cli that will automate a part of this step. So we just had to run the following command to migrate to Type-Only Imports at places needed:

The bad news: The tool didn’t find all occurrences of the Type-Only Imports, so when running npm run build, we caught some more we had to fix manually.

After your migration to Vite, you should make use of Vitest as your new pretty and fast unit testing framework. In comparison to Jest it comes with a stable out-of-the-box ESM support and faster test executions. Until now Jest’s support for ESM is still experimental (State: Jest Version 29.5). The API is quite similar and mostly compatible to jest. If you used Mocha before, the migration shouldn’t be hard either.

The next big step you should do in advance is the migration of your Vuex store. You can also do this step after the migration itself and keep Vuex for now. However, we decided, it’s a good idea, to migrate the store before and switch to Pinia since the API is a lot simpler and better composable when slicing our big store into chunks. Furthermore, it comes with better TypeScript support. At the Pinia-Docs you will find a very detailed Guide for the Migration from Vuex

Last but not least we decided to migrate all our components to the composition API with the <script setup> syntactical sugar. This is a step you can also omit or do in advance, but we recommend using this API since it’s also a bit more performant, and it reduces the boilerplate code you have to write.

Here we started by adding Vue 3 as well as the @vue/compat package as described in the Vue 3 Migration Build documentation. Also, we needed to update the VueRouter to version 4.x.x and adjust the configuration. As good step-by-step guides, I would recommend you again to read the following Blogposts:

If you have already prepared some components in isolation to work with Vue 3 as we did: Of course you should replace the old ones and probably adjust the props or events if the API of your new components changed compared to the Vue 2 ones.

After this step your whole app should work as before (fingers crossed). The migration of the components itself can be done one by one after the migration until everything is converted to Vue 3.

After you migrated everything, you need to update to @vue/test-utils@v2. The migration should be straight-forward when following the migration guide. Nonetheless it can take quite a bit of time depending on the amount of unit tests you have.

Once every component is migrated, make sure to remove the @vue/compat and it’s configuration as you don’t need it anymore.

Now that we are using Vue 3, we can use the "Teleport" feature. Think about components creating their DOM elements deeply in the DOM caused by the component hierarchy but where you would expect the elements to appear somewhere else close to the root. A good example is displaying a modal conditionally:

In Vue 2, the modal would be rendered and appear inside the ComponentThree. Using teleport in MyModal can lift the element up to the body tag which makes more sense for common modal dialogs.