Building custom elements from Vue using the CLI
If you’re working in Vue, the Vue CLI is an amazing thing. There are a lot of moving parts in modern JavaScript development and the CLI makes managing these very easy.
One of the niceties that the CLI will give you is the ability to compile your Vue components into custom HTML tags. I’ve talked about how to get this set up in What are custom HTML elements and in Building custom elements from Vue CLI. This article is about how to then compile and export those components so that they are ready to put on any web page.
Transpiling Vue to Custom Components
The process of turning Vue into an official, browser supported Web Component is handled via a Vue build tool called @vue/web-component-wrapper
. This will take your component and build it into the format needed by the Web Component standard. This transpiling from a Vue component to a custom component is already built into Vue CLI, so if your project was created with Vue CLI, all you have to do to export a component to a custom component is this:
vue-cli-service build --target wc --name my-blink 'src/components/Blink.vue'
This will create three files in your dist
folder:
Filename | Purpose |
---|---|
my-blink.js | The code for your component minus the Vue library |
demo.html | A simple demo HTML file for your component |
my-blink.js.map | The debugging information for your browser |
my-blink.min.js | The minified version of the component |
my-blink.min.js.map | The debugging information for the minified version |
The important thing to know here is that you must include the Vue library in your HTML wherever you want to use your component. It’s not included in the build itself. If you look at the demo HTML file that was created during the build process, you’ll see that in action.
<script src="https://unpkg.com/vue"></script>
<script src="./my-blink.js"></script>
<my-blink></my-blink>
You can then use that demo.html
file to test out the component.
What if you have more than one component?
What if you have multiple components that you want to turn into Web Components? You don’t need to build each one individually, you can instead build them all at once.
vue-cli-service build --target wc-async --name demo 'src/components/*.vue'
This will build your components into multiple files that are actually lazy loaded into the browser. If you don’t use a certain component, its file won’t be loaded in. Nice!
But what about the --name
? When you defined that in your single component build, it made the tag that name. But here you have multiple components. What does it do now?
Here, --name
is used as a prefix for your tags. So if your Vue component is named blink
and the --name
is defined as demo
, then your tag will export as demo-blink
.
And that’s it
Now you can build your Vue components, take the js
files from dist
and drop them onto any web page. Then just include the tag anywhere in your HTML and BOOM Vue components on any page.