Hero image

Build web component with Stencil


In the previous post, I discussed why I think web components are awesome and some of the potential concerns that might stop people from invest in using this technology.

The Ionic team has developed a web component compiler called Stencil. I've been using it to build my personal projects, including this site you're looking at. (Source).

Stencil is a tool that helps you build reusable, framework-agnostic, standard-complaint web components with modern framework-like developer experience.

Why Stencil

There are many reasons to use Stencil for your next project, and the stencil team has built some awesome tools to make it easier to build full apps (such as router and store). We keep our attention to the core functionality here which is building web components, here are some benefits of using the Stencil compiler:


Stencil provides a tiny virtual dom layer for developers to build components the way they are used to with React or Vue, in fact, the syntax of a component looks very similar to a React component, here's an example that is taken from the latest version of ionic, which is built using Stencil



If you've been coding react you'll see a couple of strange bits like the @Component decorator (https://stenciljs.com/docs/decorators#decorators) and special components such as Host and slot (https://stenciljs.com/docs/host-element) but other than that it's pretty much the same so if you're comfortable with React, you'll be able to pick up Stencil in no time.

Lazy loading

What is lazy loading? It means if there are hundreds of components in the design system, only the ones that are used in the current page will be loaded to the users. This reduces the need for individually packaging up every component and publish them with mono-repos and package managers like Lerna. It also means the page load will be super fast since there's only the minimum amount of extra code required to load everything necessary.

More details on lazy loading: https://stenciljs.com/docs/faq#why-does-stencil-allow-components-to-be-lazy-loaded

Dev environment

A good local environment is essential for rapid front-end development. Developers need a simple command to spin up a local server, watch your file change and have those changes appear in the browser immediately. Simply `npm start` in your directory and all of above is taken care of.

More details on dev server: https://stenciljs.com/docs/dev-server

Automatic polyfill

If you need to support older browsers like IE11, you'll need polyfills. With Stencil, this is, again, taken care of, and it loads up polyfill scripts only in old browsers so that the performance stays top-notch.

Automatic docs generation

Most of the time when you build a component, you want it to be reusable by your teammates, other developers in the wild, and your future self. Documentation plays a big part in that knowledge sharing process, however, writing documentation can be daunting. Generating documentation from code can really help remove the extra work you have to do as a developer.

The quality of the generated documentation is really good. It automatically picks up what data should be passed in from each property, what events does the component emit, what methods are available in this component for global use, the slots can be used in the component, even the CSS variables that the component uses which you can change in the glocal context.

You can easily build a documentation site with the generated markdown files, here's an example.

You can customise a lot of the documentation generation process too to fit your use cases.

More details on documentation: https://stenciljs.com/docs/docs-readme


Stencil also allows you to use CSS preprocessors like Sass and Less as well as PostCSS. This is done using stencil plugins. These plugins are quite easy to configure and well documented. If you're like me, the @stencil/sass and @stencil/postcss plugins are essential to add to the project.

How do I get started?

To start building web components with Stencil, just run this simple command

npm init stencil and select the component option in the prompt.

Then get your hands dirty with the assist of the official docs, there are so many great resources available too at https://stenciljs.com/resources


Hopefully, this post provided some insights and got you started working on your first web component. There are many tools out there to help you with your needs, Stencil is one of them I enjoy using very much. I encourage you to give it a go, I think you'll love it! And maybe use it to build your next design system!