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 theGlobal APIsee reference.

Vue contributor@posva stated in thisgithub 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:

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

// main.jsimportVuefrom'vue';importAppfrom'./App.vue';newVue({render:h=>h(App),}).$mount('#app');

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

// main.jsimportVuefrom'vue';importVueToastedfrom'vue-toasted';Vue.use(VueToasted,{...options});

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

// vue-toasted/src/index.jsconstToasted={install(Vue,options){if(!options){options={};}constToast=newT(options);Vue.component('toasted',ToastComponent);Vue.toasted=Vue.prototype.$toasted=Toast;},};

In 3.x the app instance is created troughcreateApp:

// main.jsimport{createApp}from'vue';importAppfrom'./App.vue';constapp=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

constapp=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:

constapp=createApp(App);app.use(VueToasted,{...options});

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

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

The Solution

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

constVueToastedPlugin={install(app,options){if(!options){options={};}constToast=newT(options);app.component('toasted',ToastComponent);app.config.globalProperties.$toasted=Toast;},};exportdefaultVueToastedPlugin;

You may notice two subtle changes:

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

Now, you will be able to useapp.use(VueToasted, {...options});. In the specific case ofvue-toasted library you will normally create a new toasted message accesing the$toasted onthis:

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 thesetup() method, a lot of libraries today inject properties ontothis. Let's take another example,Vue Router injectsthis.$route andthis.$router, andVuex injectsthis.$store.

When using the Composition API, since there is nothis. Plugins will leverageprovide andinject internally and expose a composition function. Let's continue usingvue-toasted as an example:

// useApi.jsimport{inject}from'vue';exportconstVueToastedSymbol=Symbol();exportfunctionuseToasted(){constVueToasted=inject(VueToastedSymbol);if(!VueToasted)thrownewError('No VueToasted provided!!!');returnVueToasted;}

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

import{ToastedasT}from'./js/toast';importToastComponentfrom'./toast.vue';import{VueToastedSymbol}from'./useApi';export*from'./useApi';constVueToastedPlugin={install(app,options){if(!options){options={};}constToast=newT(options);app.component('toasted',ToastComponent);app.config.globalProperties.$toasted=Toast;app.provide(VueToastedSymbol,Toast);},};exportdefaultVueToastedPlugin;

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('CompositionAPIBABYYY!', {      position:'bottom-right',      duration: 5000,    });  },};

Conclusion

You might be thinking, why the plugin authors are not doing this already 🤔? Most of the core libraries likeVue-router andVuex 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 didhere 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 onSep 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 basemaster but it should be aiming to a/next branch on the base@shakee93 so both2.x and3.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{ToastedasT}from'./js/toast';importToastComponentfrom'./toast.vue';import{VueToastedSymbol}from'./useApi';export *from'./useApi';constVueToastedPlugin={install(app,options){if(!options){options={};}constToast=newT(options);app.component('toasted',ToastComponent);app.config.globalProperties.$toasted=Toast;app.provide(VueToastedSymbol,Toast);},};exportdefaultVueToastedPlugin;

Now instead of Vue, theapp instance is passed so it will work with the newcreateApp, and the global property will be available onthis by usingapp.config.globalProperties.$toastedreference

constapp=createApp(App);app.use(VueToasted,{ ...options});

In Vue 3.x plugins will leverageprovide andinject internally and expose a composition function.

To do that I add auseApi.js for the use of the library along with the Composition APIreference:

// useApi.jsexportconstVueToastedSymbol=Symbol();exportfunctionuseToasted(){constVueToasted=inject(VueToastedSymbol);if(!VueToasted)thrownewError('No VueToasted provided!!!');returnVueToasted;}

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

import{useToasted}from 'vue-toasted`;constComponent={setup(){consttoasted=useToasted();toasted.success('Composition API BABYYY!',{position:'bottom-right',duration:5000,});},};

To support the last release candidate vue3.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'.