// I need to

ModernizeUpgrade without breaking it RescueFix what someone else started Build NewTurn an idea into a product Reach More PeopleGet found, get used, include everyone

// Company

Case StudiesExpertiseAbout + CareersResourcesContact Book a call →
≡articleModernize

Smooth Upgrades to Vue 3

Vue 3 brings the Composition API, a faster Proxy-based reactivity system, and Vite. How the migration build makes upgrading a Vue 2 app smooth and gradual.

Paul Hendry Jul 1, 20215 min read

From the Art+Logic archive · written in 2021. The tools may have moved on; the thinking still holds.

Smooth Upgrades to Vue 3

This post assumes basic familiarity with Vue.js v2.x.

Vue 3, the Progressive JavaScript Framework, introduces some compelling new features:

It’s a valuable upgrade in terms of performance and developer productivity. The question is, how do you get there? While v3 does not make any drastic API changes compared to v2, the changes it does make are numerous, and as of the initial v3.0 release, these breaking changes would need to be migrated in one fell swoop.

Fortunately, the Vue.js team has recently released the Migration Build, which makes it possible (and easy) to make a smooth transition from v2 to v3.

Vue 3 Compatibility Caveats

There are a few reasons why you might not be ready to introduce Vue 3 into your project:

Make sure that your project’s dependencies and supported platforms allow for the upgrade. If not, keep in mind that some v3 features are being backported to v2, such as the Composition API.

What is the Migration Build?

The Migration Build is an alternative build of Vue 3 which provides configurable Vue 2 compatible behaviour. It enables a gradual migration process:

  1. Swap out your vue v2.x dependency with @vue/compat;
  2. Configure the Migration Build to be fully v2-compatible;
  3. One breaking change at a time, configure the Migration Build to be v3-compatible for that feature, and fix any occurrences of it in your project;
  4. Swap out @vue/compat for vue 3.x once your project is fully migrated to v3.

The amount of overhead introduced by this compability build is relatively small, so it’s even possible to make releases while in the intermediate state between v2 and v3 compatibility. The Vue.js team has guaranteed to maintain this migration build at least until the end of 2021, but after that no firm commitments have been made, so if you’ve made the decision to upgrade, it’s best not to delay for too long.

Using the Migration Build

The first step of course is installation, and the official installation documentation is easy to follow.

Configuration is straightforward, and can be done both globally or on a per-component basis. A global configuration can be created with a snippet like this in the root of the application:

import { configureCompat } from 'vue';

configureCompat({
   // By default, each feature is v2 compatible. Set individual features to
   // `false` like so to switch them to v3 compatibility.
   GLOBAL_MOUNT: false,
});

Once installed and configured, your v3-upgraded application should, for the most part, function just the same as before. From here, the Feature Reference in the official documentation is where you’ll find a list of the individual v3 features to enable in order to migrate your project. They’re separated into four “Compatibility Types”, in a sensible order for sequentially working through them. These are:

For each feature, simply migrate each v2-style occurrence, then set FEATURE_NAME: false in your compatibility configuration in order to switch the Vue build to use the v3 behavior.

For example, consider the INSTANCE_SCOPED_SLOTS compatibility feature. The Feature Reference provides a link to the relevant migration documentation, which tells you that this.$scopedSlots has been removed due to the unification of normal/scoped slots in v3. The “Migration Strategy” section at the bottom describes simple steps to take: replace occurrences of this.$scopedSlots with this.$slots, and then replace occurrences of this.$slots.mySlot with this.$slots.mySlot(). This can easily be done in a few moments using find-and-replace, after which INSTANCE_SCOPED_SLOTS: false can be set in your compatibility configuration, one step closer to v3 compatibility.

Recap

Overall, the Migration Build allows for a gradual development process of migration that looks something like this:

  1. Replace your project’s Vue 2.x dependency with the Vue 3 Migration Build

  2. Install and configure it for full v2 compatibility

  3. Migrate the handful of features marked “Incompatible” in order to restore your application to full function

  4. Peform some smoke testing to ensure that everything is back to normal

  5. Merge this change into your mainline development branch

  6. Continue regular development as required, potentially even making releases along the way

  7. While numUnmigratedFeatures > 0,

  8. Use the Feature Reference documentation to identify the next compatibility feature to disable

  9. Switch to v3 behavior by setting FEATURE_NAME: false in your Migration Build configuration

  10. Use the documentation link in the Feature Reference to jump to relevant information about how to migrate to v3

  11. Migrate all occurrences in your project

  12. Merge this change into your mainline development branch (which ensures that any subsequent commits must use the v3 behavior)

This easy and comprehensive upgrade process, combined with how infrequently Vue makes breaking API changes to begin with, arguably makes it best-in-class among JavaScript UI framworks in terms of long-term maintenance (although React is introducing a similar upgrade process for the upcoming version 18). It’s one of the reasons why we recommend Vue.

keep going

More to explore in Modernize.

All Modernize resources →
let's talk

Got a problem like this one?

Tell us what's stuck. A real person replies within one business day.

Talk to our team →

Talk to people who know software, not a sales script.

Your first call is with Aja, our VP of Sales. He'll help make sure you're solving the right problem. Here's what you'll cover together:

  1. What you're trying to accomplish

    The business goal first, then the technology.

  2. Possible approaches

    And the tradeoffs of each, in plain language.

  3. Risks you may not have considered

    Technical and business, before they cost you.

  4. Whether AI changes the math

    What's practical, and what's just hype for your project.

  5. Sensible next steps

    Even if the right next step is not us.

book-a-call.ics

Loading the scheduler…

Open the booking page →

Some problems are easier to explain in writing. Send us a few lines about what you're working on, and we'll reply within one business day. Helpful to include:

  1. What the software does, or should do
  2. What's stuck, or what's worrying you
  3. Any deadline or budget you have in mind
note.md

Loading the form…