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:
- app instance is passed as a parameter of the install method, so now instead of doing
Vue.component
we doapp.component
- To add a global property,
Vue.prototype
becomesapp.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
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
That's all folks, keep it rockin'.
Top comments (8)
useApi.js
code block you are not showing where theinject
function comes from. Maybe worth adding?next
) branch to add support for Vue3. Is there anything blocking one from adding support on the existing branch as a new feature?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
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?
Hello Emmanuel, thanks for reaching out
I hope this clarifies your doubts. If you have any other, feel free to ask.
Happy coding.
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 useapp.component
as you showed in the article and someone using Vue 2.x.x installs my package and then call it withVue.use(packageName)
in theirmain.js
, will this process work?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 :
I get an error in the console :
Maybe I'm doing something wrong or misunderstanding... do you have an idea of why this error is happening ?
Thank you !
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...
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.