How to migrate your library from Vue2 to Vue3

Vue 3 is just around the corner. The hype is real so you might be tempted to start migrating all your existing projects to the new version. Before doing that I will save you some pain with this simple question:

Does your app heavily depends on third party libraries like (BootstrapVue, Vuetify, etc)?

If the answer is yes, you might want to stop the process for a moment.

Why?

Most of Vue plugins and third-party libraries will not work on Vue3 (yet) due to the breaking changes on the Global API see reference.

Vue contributor @posva stated in this github thread:

In this article, I will show you how to migrate a Vue 2.x library to Vue 3.x plugin, so if you are the owner of a library or just a user that wants to contribute to your favorite carousel plugin to migrate to Vue3 this tutorial is for you.

The new global API

One of the major breaking changes introduced on Vue 3.x is how the app is created:

In 2.x global APIs and configurations globally mutate Vue's behavior

// main.js
import Vue from 'vue';
import App from './App.vue';

new Vue({
  render: h => h(App),
}).$mount('#app');

For instance, you want to add vue-toasted library into your project, you would use Vue.use and pass the library object with the options:

// main.js
import Vue from 'vue';
import VueToasted from 'vue-toasted';

Vue.use(VueToasted, { ...options });

Under the hood, what VueToasted does, extends the Vue instance and declare some components (Vue.component) and global objects into it (Vue.prototype):

// vue-toasted/src/index.js

const Toasted = {
  install(Vue, options) {
    if (!options) {
      options = {};
    }

    const Toast = new T(options);
    Vue.component('toasted', ToastComponent);
    Vue.toasted = Vue.prototype.$toasted = Toast;
  },
};

In 3.x the app instance is created trough createApp:

// main.js

import { createApp } from 'vue';
import App from './App.vue';

const app = createApp(App);

An app instance exposes a subset of the current global APIs. The rule of thumb is any APIs that globally mutate Vue's behavior are now moved to the app instance like this

const app = createApp(App);

app.component('button-counter', {
  data: () => ({
    count: 0,
  }),
  template: '<button @click="count++">Clicked {{ count }} times.</button>',
});

app.directive('blur', {
  mounted: el => el.blur(),
});

So you might be tempted to do:

const app = createApp(App);

app.use(VueToasted, { ...options });

Uncaught TypeError: Cannot set property '\$toasted' of undefined

Why? Because in the vue-toasted library the property is added to 'Vue': Vue.toasted = Vue.prototype.$toasted = Toast;

The Solution

Actually, is pretty simple, let's remove the old plugin/index.js and create a plugin object:

const VueToastedPlugin = {
  install(app, options) {
    if (!options) {
      options = {};
    }
    const Toast = new T(options);
    app.component('toasted', ToastComponent);
    app.config.globalProperties.$toasted = Toast;
  },
};
export default VueToastedPlugin;

You may notice two subtle changes:

1. app instance is passed as a parameter of the install method, so now instead of doing Vue.component we do app.component
2. To add a global property, Vue.prototype becomes app.config.globalProperties

Now, you will be able to use app.use(VueToasted, {...options});. In the specific case of vue-toasted library you will normally create a new toasted message accesing the $toasted on this:

methods: {
   showToast() {
      this.$toasted.show('How you doing?');
   }
}

With Composition API

So we manage to take a random Vue library without Vue 3.x support into the new standard. The previous code will work perfectly with the options API but what about using it along of one of the most interesting and new features of Vue3, the composition API?

Yes, this is not accesible in the setup() method, a lot of libraries today inject properties onto this. Let's take another example, Vue Router injects this.$route and this.$router, and Vuex injects this.$store.

When using the Composition API, since there is no this. Plugins will leverage provide and inject internally and expose a composition function. Let's continue using vue-toasted as an example:

// useApi.js
import { inject } from 'vue';

export const VueToastedSymbol = Symbol();

export function useToasted() {
  const VueToasted = inject(VueToastedSymbol);
  if (!VueToasted) throw new Error('No VueToasted provided!!!');
  return VueToasted;
}

then we provide into the app instance --> app.provide(VueToastedSymbol, Toast);

import { Toasted as T } from './js/toast';
import ToastComponent from './toast.vue';
import { VueToastedSymbol } from './useApi';
export * from './useApi';

const VueToastedPlugin = {
  install(app, options) {
    if (!options) {
      options = {};
    }
    const Toast = new T(options);
    app.component('toasted', ToastComponent);
    app.config.globalProperties.$toasted = Toast;
    app.provide(VueToastedSymbol, Toast);
  },
};

export default VueToastedPlugin;

So now, in any setup method or composition function we can do:

import { useToasted }  from 'vue-toasted`;

const Component = {
  setup() {
    const toasted = useToasted();

    toasted.success('Composition API BABYYY!', {
      position: 'bottom-right',
      duration: 5000,
    });
  },
};

Conclusion

You might be thinking, why the plugin authors are not doing this already 🤔? Most of the core libraries like Vue-router and Vuex already have a /next branch and beta releases with the support for vue3 and even with Typescript as default but the rest of third party libraries are open source, and believe, is hard to keep your library updated by your own(we have limited hours per day) without contribution for other developers.

So, did you find out the awesome library you were working with for your toast message isn't working for vue3? Make a PR like I did here to the library with the stuff you learn today. Not only it will be highly appreciated by the authors of the plugin but also will give you a higher level of knowledge in Vue. You will contribute to the community 😊.

WIP: new global api install + composition provide + update deps #180

alvarosaburido posted on Sep 01, 2020

Hello,

This PR is meant for migrating the library to be used in Vue 3.x (is in Work in Progress), the PR set to base master but it should be aiming to a /next branch on the base @shakee93 so both 2.x and 3.x solutions coexist in the same repo. If this branch is created I will change the destination of the PR

Basic changes:

vue-toasted/index.js :

import { Toasted as T } from './js/toast';
import ToastComponent from './toast.vue';
import { VueToastedSymbol } from './useApi';
export * from './useApi';

const VueToastedPlugin = {
  install(app, options) {
    if (!options) {
      options = {};
    }
    const Toast = new T(options);
    app.component('toasted', ToastComponent);
    app.config.globalProperties.$toasted = Toast;
    app.provide(VueToastedSymbol, Toast);
  },
};

export default VueToastedPlugin;

Now instead of Vue, the app instance is passed so it will work with the new createApp, and the global property will be available on this by using app.config.globalProperties.$toasted reference

const app = createApp(App);

app.use(VueToasted, { ...options });

In Vue 3.x plugins will leverage provide and inject internally and expose a composition function.

To do that I add a useApi.js for the use of the library along with the Composition API reference:

// useApi.js

export const VueToastedSymbol = Symbol();

export function useToasted() {
  const VueToasted = inject(VueToastedSymbol);
  if (!VueToasted) throw new Error('No VueToasted provided!!!');

  return VueToasted;
}

So now, in any setup method or composition function we can do:

import { useToasted }  from 'vue-toasted`;

const Component = {
  setup() {
    const toasted = useToasted();

    toasted.success('Composition API BABYYY!', {
      position: 'bottom-right',
      duration: 5000,
    });
  },
};

To support the last release candidate vue 3.0.0-rc.9 I needed to update several packages from the package.json, this is causing errors in the webpack build process, especially with the uglify plugin:

cross-env NODE_ENV=production webpack --config ./build/webpack.release.js --progress --hide-modules

/Users/alvarosaburido/as/github/as-vue-toasted/node_modules/webpack-cli/bin/cli.js:93
                                throw err;
                                ^

Error: webpack.optimize.UglifyJsPlugin has been removed, please use config.optimization.minimize instead.
    at Object.get [as UglifyJsPlugin] (/Users/alvarosaburido/as/github/as-vue-toasted/node_modules/webpack/lib/webpack.js:189:10)
  

If someone from the core team is available to help me out with this I think is ready to be used (already tested as a submodule in a personal project).

Feel free to contact me directly if needed.

Happy Coding

View on GitHub

That's all folks, keep it rockin'.

Comments

[Rafał Chłodnicki]

• In the useApi.js code block you are not showing where the inject function comes from. Maybe worth adding?
• It looks like the convention for "native" Vue libraries is to use a separate (next) branch to add support for Vue3. Is there anything blocking one from adding support on the existing branch as a new feature?

[Alvaro Saburido]

Good catch, I will add it, it's important to be added

For the second one yes is good to use "next" branch is also referencing to npm channel next where you can install from a certain tag version . Lets see it with the following practical example

Your library for vue2 is currently on version 1.2.0, you create a branch called next, that is going to be some kind of a "master/develop" branch for the new version, and you start there from 2.0.0, you would do the same git flow as you normally do, create a feature branch, or bugfix from next and merged into next.

That way in the same repo you mantain a 1.x.x version for vue2 and a 2.x.x of the library for vue3. When you feel the next version is ready you can merge it into master so its your stable version of the package.

I would suggest to wait a little to do that, in the meantime suggest your user to install the vue3 compatibility version trough 'npm i your-awesome-lib@next'

I hope it helps, if you have more question feel free to write me, and thanks for the feedback

[Emmanuel Raymond]

Thanks for the article:)

I have some follow-up questions:

• Does that mean all you have to do to migrate an existing library is to do as the article suggest? Is there something else to do when migrating (I'm assuming you have to update some dependencies like Vue from 2.x.x to 3.x.x)?

• Can I also use the next version the same way as the main version? Say I install the @next version but don't want to use it with composition API, will this work?

[Alvaro Saburido]

Hello Emmanuel, thanks for reaching out

1. Yes, you have to update vue to 3.x version, and all related dependencies. This article covers adapting the installation of the plugin to the new standard in vue 3.
2. Composition API is purely additive, so the library would work exactly the same if use with the Options API. It does depends if they're more breaking changes other than the installation added by the authors. In that case they should be reflected in a proper "Migration Guide" in the documentation.

I hope this clarifies your doubts. If you have any other, feel free to ask.

Happy coding.

[Emmanuel Raymond]

Thanks for your reply. This reason I ask is that I'm planning on making a package and from what I have read, I can just go ahead and use the new standard and it will work for both Vue 2 and Vue 3, yeah?. This is what I need clarification on.

Since Vue.component isn't available for plugin in Vue 3, if I use app.component as you showed in the article and someone using Vue 2.x.x installs my package and then call it with Vue.use(packageName) in their main.js, will this process work?

[denrique88]

Hi !

I'm learning Vue and I started a personal project using Vue 3.0.
Many libraries are not ready to use with Vue 3, so I was interested by your article. Thank you ! I wanted to test your changes in Toasted in my project.
So I installed Toasted with npm targeting the github repo on #next branch.

Unfortunately, I wasn't able to do it work.
When adding Toasted in my main.js file :

import Toasted from 'vue-toasted';

const app = createApp(App);
app.use(store)
.use(router)
.use(Toasted)
.mount('#app');

I get an error in the console :

Uncaught TypeError: t.prototype is undefined
    install vue-toasted.min.js:1
    use runtime-core.esm-bundler.js:3164

Maybe I'm doing something wrong or misunderstanding... do you have an idea of why this error is happening ?

Thank you !

[Alvaro Saburido]

Hey!

Even if I did the PR to vue-toasted library and was merged, I think they haven't finished migrating for support of vue3 yet, I would suggest opening a ticket here github.com/shakee93/vue-toasted/is...

[John zuo]

Hi Alvaro, Thanks for your article. I am wondering what is the "plugin/index.js", how can I update it. I found there is a new branch on github. But I do not know how to update the lib with the "next" branch? Thanks for your time to read this.