How to create a Universal Library for Vue 2 & 3

As you probably know by now, last September Evan You announced the new version of Vue (Vue 3.0 or "One Piece" for friends) during the Vue.js Global Event - Official release here.

The hype for upgrading code to the latest version of Vue exploded and everyone (including me) was eager to start. But they are breaking changes, especially on the global API, forcing library/plugin authors to migrate their code to support the new version and the Composition API. If you want to understand better why I wrote an article on how to do the migration from 2.x to 3.x here - How to migrate your library from Vue 2.x to Vue 3.x

As an author of a Vue library, I have to say that the migration wasn't an easy job, imitating what major libraries did: separating the support for each the targeting version in separate branches and tags (main for vue 2.x and next for vue 3.x) or even having a separate repo to ensure better code isolation.

As Vue.js core member @antfu (Anthony Fu) explains in this post:

It's possible to achieve this by using a developing tool that the same @antfu created called Vue-demi.

So if you are interested to learn how to create a universal library/plugin for both versions of Vue, this article is for you.

Let's begin by creating a new project using vue-cli prompt.

Be sure you select the 3.x version for Vue, and the rest I leave it to your preferences, but I strongly suggest you use the same options as I describe here to be on the same page: Options selected:

Babel

Typescript

Linter

Use class-style component syntax No

Use Babel alongside TypeScript Yes

Pick a linter: ESLint + Prettier

After some seconds we will have a basic structure to start with. You probably need to get rid of some stuff like the App.vue and main.ts since we mainly are going to work with an index.ts file.

Sounds epic right? Fun apart find a necessity, some functionality often used in Web development that you want to implement in Vue and make it reusable, something that you think will bring value being a library/plugin.

For this tutorial sake, we will create a simple library that allows you to animate numbers like a counter, similar to this:

This type of component is often used in landing pages to show KPIs.

First of all, let's create the counter-number component under src/components/CounterNumber.ts using defineComponent.

For the moment let's leave it as a presentational component without the animation, later we will add the functionality through a composable function to take advantage of Vue3's Composition API.

You might also notice there is no template for the component in here, the setup function returns a render function with a <span> element holding the counter value. That's intended and will be explained in the Caveates section of the post.

For demo purposes leave out a main.ts and the App.vue to test the new component using npm serve.

For creating the plugin itself create a src/index.ts:

Let's break this down into parts, the function createVueCounterPlugin will allow you to install the plugin via the install method when using createApp.use() in your app.

This will add to the app instance all the components, properties of your library like you see above with app.component('vue-counter', CounterNumber);

To get most of the Composition API and be able to inject into your library components things like options or utilities we create a Plugin Symbol to be used along with app.provide in the install method where we pass the createVueCounterPlugin itself as a parameter. This might look complicated at the moment, but it's the standard way:

To install the plugin and test it, go to your src/main.ts:

If you like to pass options to your plugin you can do it like this

The magic behind what we did is that using app.provide in the plugin install method is that we can inject the plugin options as a dependency later.

Now let's add the CounterNumber component into the src/App.vue.

If you are curious about the utility classes I used here, is the awesome TailwindCSS which I love for doing quick prototypes. You can install it also by following this guide. Just make sure you add those dependencies as devDependencies to your package.json or they will be included in your library bundle.

Let's see how it looks on the browser with npm run serve

Looks beautiful, but needs more magic. Let's add the easing animation for the counter. To achieve a smooth animation, we will be using a library called anime.js, which is really lightweight and offers and plain simple API.

We could add the logic directly on the CounterNumber component, but since we talked before about Composition API let's use it for this purpose.

Create a useCounter.ts file under src/composables and export a function called useCounter like this:

We import a factory function called 'anime' from 'animejs/lib/anime.es.js' and we pass a target (in this case an obj containing a ref with the value to be animated).

The anime() function accepts a lot of parameters to customize the behavior of the animation such as duration, delay, easing, and callbacks like an update that triggers every time the animation updates the target object. The interesting thing is that you can pass as property the same property you want to animate, in this case value, in the example above will go from 0 to 640. For more info about the animejs API check the docs

Go back to your CounterNumber.ts component and get the use the count.value inside the span like this:

Now go back to the browser and refresh to see how the counter goes from 0 to 640 in 2 seconds.

At the moment, all values are hardcoded, but since we are doing a library, these parameters for the animation should be customizable and therefore passed as props to the component and down to the composition function.

First, let's add some props that make sense:

Make sure you pass the props to the useCounter(props) function;

Go to App.vue and create some variables to pass to the component as props:

Finally, go back to useCounter.ts and pass the props to the anime instance

Of course, we would need to add more code to make it create a new instance of the anime object every time a prop change, but for the scope of the article is more than enough.

So great, we have our awesome library ready, at the moment, is only usable on a project with for Vue 3, how can we achieve an isomorphic installation?

That's where vue-demi comes to the rescue.

Add vue and @vue/composition-api to your plugin's peer dependencies to specify what versions you support.

Now comes the important part 📝, to take notes on it: replace all the imports coming from vue to vue-demi, like so:

Will become:

The library will redirect to vue@2 + @vue/composition-api or vue@3 based on users' environments.

That's powerful.

You can build your plugin bundle in so many different ways, webpack, vue-cli (webpack also), parser, rollup, etc. It's up to you, but I really recommend using rollup.js, is a great module bundler, really easy to get into, and is used in most of the major Vue plugins out there, such as Vue Router.

Also, we will need to tweak a little bit the configuration so it externalizes vue-demi instead of vue and set it as a global at the build moment. Because the rollup.config.js is quite large, here is the link to it at the example repo.

In the method createConfig make sure you have vue-demi set in the property globals like this:

Finally, let's add a script in the package.json and the paths for the package builds:

Of course, is not all roses 🌹 and unicorns 🦄, the use case of vue-demi is rather for vue plugins that don't rely too much on rendering components because Vue 2 and Vue 3 render functions are quite different and the breaking changes between both, i.e. v-model on a component expecting differently named events in Vue 2 vs 3 (ìnput vs update:modelValue).

That's why we used a render function for our component definition and a .ts file instead of a .vue file. For this example library, it will not affect the end result but it's something you need to take into consideration.

One way to possibly adapt breaking changes in your lib component would be the use of extra APIs from Vue Demi to help distinguishing users' environments and to do some version-specific logic.

isVue2 isVue3

That being said I hope this article was illustrative enough on the journey of creating a universal plugin for Vue. Let me hear your thoughts and questions below.

Happy coding! 😎