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'.