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

The Vue maintainers provide @vue/compat: the Vue 3 runtime with configurable Vue 2-compatible behavior. It does not run Vue 2 and Vue 3 side by side, but it can let many Vue 2 APIs continue working while you migrate incrementally. Compatibility behavior can be disabled globally or per component.

Choose one Vue 3 version and install the runtime, compatibility build, and SFC compiler at that exact same version. Remove vue-template-compiler if the project still uses it.

npm remove vue-template-compiler
npm install --save-exact vue@3 @vue/compat@3 @vue/compiler-sfc@3

Then alias vue to @vue/compat and start in Vue 2 compatibility mode. For a Vite project:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  resolve: {
    alias: { vue: "@vue/compat" },
  },
  plugins: [
    vue({
      template: {
        compilerOptions: {
          compatConfig: { MODE: 2 },
        },
      },
    }),
  ],
});

See the official migration-build installation guide for webpack configuration, TypeScript augmentation, and known limitations.

Install and configure ESLint to catch common Vue issues. Current ESLint uses a flat eslint.config.js file:

npm install -D eslint eslint-plugin-vue

import pluginVue from "eslint-plugin-vue";

export default [...pluginVue.configs["flat/recommended"]];

The compatibility build can keep much of the application running while warnings identify behavior that still needs migration. Review its known limitations before committing to this path; some applications and dependencies cannot use it safely.

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 before switching from @vue/compat to Vue 3 proper. Disable compatibility features in tested batches and resolve the resulting warnings.

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.