5 opinionated Vue 3 migration tips

By now, you most likely have heard about Vue 3 - the next major version of Vue. More than that, given the extended pre-release period of Vue 3, you might have already used it.

Vue 3 brings to the table a lot of changes. TypeScript rewrite, Composition API, fragments, improved JSX support - that’s just a few of my top picks. No wonder why so many developers have already jumped on the train with full steam ahead, despite the persistent beta status.

With that said, in this group of developers, we can distinguish 2 separate ones - one that’s jumping directly into Vue 3 and the other one that is already deep into Vue 2 and wants to proceed with the migration to reap the benefits.

As someone who’s somewhat between the 2, I’ve got some tips for both groups. I’ve already worked extensively with Vue 2 and its ecosystem in the past and only recently came back to use Vue 3 for powering my CodeWrite code-blogging tool. This experience gives me a pretty special look into the Vue 2 - Vue 3 migration, which today I’d like to share with you in the form of opinionated, useful tips!

1. Mind the ecosystem

I think that the official migration docs don’t stress that enough. Vue 3 maintains a big chunk of the Vue 2 API as it was, but it still has some breaking changes. And because of these changes, you lose access to pretty much the entire Vue 2 ecosystem.

Now, that’s a serious drawback. If you rely on any 3rd-party Vue 2-centric library, you’ll either have to wait for it to update or get around it on your own. When using, e.g., Vuetify (where Vue 3 support is currently in Alpha), the second option isn’t really an option, and you’ll have to wait until it’s updated.

As I started CodeWrite “fresh”, I didn’t have any ecosystem bindings holding me back. Still, the impact was noticeable, and I was severely limited in my choice of tooling. However, after spending some time searching for framework-independent alternatives and using Tailwind CSS as my “UI components library alternative”, I could get the benefits of Vue 3, framework-independence, and everything I needed to make CodeWrite a thing.

2. Tackling the breaking changes

Breaking changes don’t only affect the ecosystem - they affect your code directly. That’s why you should be well-prepared and hyper-aware of them.

It’d be ideal to get to know what will have to be changed beforehand. Check your code, do the research, make a list. You almost certainly won’t catch all issues, but you will handle the biggest ones.

You can view the full list of breaking changes on the official docs. The biggest of those are:

• Changes to the Global API and its tree-shakable restructurization
• Changes to the v-model behavior (can be problematic)
• destroyed and beforeDestroy renaming to unmount and beforeUnmount respectively
• General changes to the internal and “lower-level” APIs (relevant only if you used some custom functionalities that interacted with these APIs in Vue 2)

Mind you that these are my picks, based on my experience, and your mileage may vary. Still, the point stands, and groundbreaking changes are something to be very cautious about, even before the migration process beings.

3. Adopt new features gradually (but fast)

This one might be obvious, but there are different strategies to tackle it. So, should you really adopt new features gradually, and if so - why and how? After all, those are the main reason to do the upgrade, aren’t they?

Usually, the most common rule is to start with the new components and slowly convert the older ones. This is perfectly reasonable, but as a clean code & clean architecture freak, I’m willing to go leaps and bounds to make my code consistent.

I consider this approach equally good (the best for me), as converting my older components to the new API or code style doesn’t require that much effort. In a few cases, you can even automate it.

For Vue 3, the example of such a “code-base-wide” change would be the new Composition API or <script setup> syntax sugar. Sure, the conversion from Options API to Composition API might not seem like a “mindless”, automatable task, but it becomes increasingly easier once you convert a component or two.

Now, I know this might not be a good idea for large codebases with hundreds of components. However, the point is - don’t leave your old code to rust. Start converting it as soon as possible. Don’t wait for the need for new components to appear. Strive for consistency and cleanness.

4. Plan ahead bold moves

In connection to gradual feature adoption, let’s talk about planning. More precisely - about planning bold moves.

First off, what I mean by “bold moves”? Well, for example, adoption of TypeScript. Vue 3 has been rewritten using it, and the support is excellent now. The same can be said for other official libraries and will probably apply to most of the new ecosystem that’s being built or updated for Vue 3.

Now, is adopting Composition API, or even crazier - JSX (support for it also got better) - also a bold move? For me - no. That’s because it’s mostly just the adoption of a new feature - something expected during the upgrade, but most importantly - because it affects only the “view” part of your project.

In a well-structured project, your “business logic” should be separate from the view. Your Vue components shouldn’t have to deal with connecting to the backend, or loading resources, rather than just properly representing the current state.

So, TypeScript, without a doubt, falls into this category, as it affects your whole code-base (including business logic). Sure, you can adapt it incrementally, but you should strive for full TypeScript coverage across the board if you do.

Oh, and as this is an opinionated list, I can say that you should move to TypeScript. It’ll make your code easier to manage and more scalable while also increasing the development experience thanks to autocompletion in modern editors and IDEs.

5. Start now

With all that said, my last advice is to start now. No matter how many great tips you use or how good your project’s architecture is, migration will still take time - just less or more.

Also, there’s no way around it. The brutal truth is - you’ll eventually have to upgrade to make your product stay relevant and be able to provide new features. This, or you better start transitioning to another framework.

In case you’re highly dependant on the current Vue 2 ecosystem, you might be tempted to slow down a bit, but you shouldn’t. Instead, conduct the research on the required changes, prepare your upgrade plan, start working on compatible bits, look out for the compatibility build, and maybe even consider switching your dependencies. Making them framework-independent will make potential future changes easier and also might result in finding better alternatives.

Bottom line

Ok, so that’s been it. Now, one reminder - don’t immediately go to the comments to complain or criticize anything you’ve just read, just because it’s not the way you think it should be. Remember, it’s an opinionated list, and everyone can have different opinions. With that said, I welcome in-depth, valuable, and informative discussion.

I hope you’ve found this article helpful. If so, follow me on Twitter, Facebook, or through my newsletter (now rebooted!) for more Vue and web dev content.

Also, if you’re a technical blogger like me, consider checking out CodeWrite - free “code-blogging” tool, which treats your snippets with proper editing and formatting tools, works beautifully with Grammarly, and handles cross-posting to Dev.to, Hashnode, Medium, and Ghost blogs, with awesome auto-filling feature (did I mention it’s a browser extension?) which handles all “edge-cases” for you (e.g. converting code in Medium to GitHub Gist, or resizing large images).

Thanks for reading, and happy coding!