Some tips for your first WebComponent

Max — Thu, 18 Nov 2021 15:26:02 +0000

Over the last year I have been investigating various ways of making WebComponents. In this article I summarise what I have learnt in this process

1. Attributes with basic types

A prop is an input that can be added to WebComponents. Whenever possible, I recommend using a basic type: number, bool, string or number and avoiding Array and JSON types, although I understand that this may not be possible at times.

The problem with using an Array or JSON is that native HTML elements only allow basic attributes and there is no possible way to put an Array or JSON into an HTML template. Therefore, the only way (that I have found) is to instantiate the WC in the HTML and then reference that element in JS and add the Array or JSON attribute:

<!-- This won't work -->
<my-element my-prop-array="[1,2,3]"></my-element>
<my-element my-prop-json="{user: 'max'}"></my-element>

<!-- This will work -->
<my-element></my-element>
<script>
    document.querySelector("my-element").myPropArray = [1, 2, 3]
    document.querySelector("my-element").myPropJson = { user: "max" }
</script>

Also, it should be noted that I have found that with certain frameworks such as Angular, it is necessary to do a JSON.stringify(myPropJson) and in the WC do a JSON.parse(myPropJson), which is not the best process in my opinion.

2. Reactive vs static

You have to know the difference between a reactive and a static WC prop:

Reactive: The value of the variable that is passed to the component and the value of the prop is always the same.
Static: A copy of the value of the variable passed to the component is created in the prop.

Depending on the framework you want to use, you must indicate what you want.

3. Output with events

The way to pass data from a WebComponent to the host is mainly through events. Note that these events may be encapsulated in a CustomEvent, where the detail attribute will have the value that has been emitted.

4. Working with styles

One of the positive aspects that WebComponents bring is the use of the Shadow DOM. This is a big plus point, but on the other hand, being something relatively new, CSS development should be at its most basic. If you try to do something more complex, for example with PostCSS, you might not work or you might have a lot of difficulties.

5. Use a template

It is better if you use a template when you start the development of a WebComponent, as these templates are usually configured to do the build as well. I have developed two templates with lit and vite:

Basic concepts about WebComponents

Max — Mon, 15 Nov 2021 13:22:08 +0000

What is it?

WebComponents (WC) is a technology that focuses on the development of native web components so that they can be used by any page and any framework. To do this, an API has been developed in both JS and browsers to create these new non-native components.

When we talk about a native component we are referring to HTML elements such as: div, p, main, article, button... A non-native WebComponent would be something like <my-element></my-element>

WebComponents is a very basic API and does not have many common features for component development that we can expect from a normal framework such as: Reactive lifecycle, Reactive variables/props or Declarative template among others. That is why it is recommended to use a framework like Lit, Svelte or Angular to create WebComponents and not to do it directly on the JS API. To do this, you must compile your component with your framework to generate a JS file with the WebComponent definition. That file later you will be able to take it to any page and import the script in a similar way to:

<!DOCTYPE html>
<head>
    <script type="module" src="./simple-greeting.js"></script>
</head>
<body>
    <simple-greeting name="World"></simple-greeting>
</body>
<!-- 
    Example from:
    https://lit.dev/playground/#sample=examples/hello-world
 -->

I recommend this video to learn more about the differences between developing directly with the WebComponents API and using a framework to generate WebComponents.

I also recommend taking a look at the Open WC guidelines, recommendations and best practices.

How to generate WebComponents

As discussed above, there are two ways to create WebComponents:

Directly with the JS WebComponents API: It would be similar to building a web page only with vanilla JS and therefore I do not recommend it unless it is a very basic component.
With the help of some framework. This is what I recommend.

Webcomponents technology is just starting to be created and new tools will surely appear in the near future.

Frameworks

Good articles with more detail on this subject::

Below is a comparative table based on my personal opinion based on different tests:

Framework	Made for WC	Small bundle	External libreries^1	Buildless	FrameworkCSS	With TS^2
Lit	✅	✅	❌	✅	❌	✅
Svelte	❌	✅	-	❌	❓	❓
Stencil	✅	✅	❌	❌	❓	✅
Vue	❌	❌	✅	❌	❓	❓
Angular	❌	❌	✅	❌	❓	❓

^1 You can always use vanilla JS libraries
^2 With TS out-of-the-box

Lit

Positive facts:

Super light and fast
Well documented
No build needed, can be a negative point
Developed by Google

Negative facts:

Because it is buildless, you cannot use third party tools such as TailwindCSS with ShadowDOM.
It is a very strict CSS framework, and works with ShadowDOM, therefore, CSS works only if it is parsed using "css`h1 { color: red} ``" is allowed. More info.

Svelte

Positive facts:

Super light and fast
Well loved by the community
Well documented and lots of examples

Negative facts:

It is a framework that was intended for web development.
Small community, and therefore, few libraries/plugins compared to React/Angular/Vue.
There are certain restrictions on how Svelte is made and should be taken into account. More info

Stencil

Positive facts:

Powered by Ionic
Developed to create Design Systems.

Negative facts:

Does not have a large community

Angular/Vue

Positive points:

Popular frameworks

Negative facts:

They are not intended for developing WebComponents but web pages.
WebComponents take up a lot of space
Compared to the other frameworks in this article, both Angular and Vue are very slow to develop and build.

Storybook

Storybook is an open source tool for building components in isolation. It streamlines development, testing and documentation of the user interface. In a "story", which is a web page where a WebComponent or CustomComponent (component developed by Vue, Angular, React...) that you have developed is shown, you can interact with it by changing the props, seeing the events it emits, reading the documentation you have written about the component... which allows you to show your components and do manual testing in a much more comfortable way. Storybook can be integrated with many well-known frameworks and WebComponents.

TS

In 2021, most JS frameworks also support TS. The use of TS allows to add types to the JS. In addition, tools such as Lit or Stencil, when exporting the component, also export a document with the types of the WebComponent, indicating the props it can receive and the events it can emit and with what parameters.

Bundler

You can choose any bundler. Although Open-WC recommends the use of web-dev-server. But rollup and vite are much faster and also have a lot of plugins. The easiest is to download a template from Github.

Adding styles to WebComponents

To talk about styling in WebComponents, you have to understand that it is the Shadow DOM that allows CSS styles to be applied only to the elements of the subtree that generates your WebComponent and not to other elements of the web page that hosts the document.

This is very problematic and in general, the only thing I recommend for styling is to use the most basic method: Add classes in the HTML template and then in the CSS of the Shadow DOM by hand, this way you can ease the development process and CI/CD if you add it to the project.

Any other technique that you want to carry out in relation to the WebComponent styles can give problems:

Style inheritance

Another option (and which is not recommended in my opinion) is to disable the ShadowDOM of your component and allow your component to inherit styles from the host and, therefore, the WC developer will have to generate the JS file (with the WC definition) and the CSS. Subsequently, the WC user would have to import both the JS file and the CSS file. These styles will also be applied to the host.

Svelte, for example, uses this technique with the difference that it hashes the CSS classes and in the end the expected result is achieved: That the CSS classes are only applied to the WebComponent. In this way, tools like PostCSS could be used for the development of the WebComponent and not only vanilla CSS.

Still, ShadowDOM is a very immature technology and it is possible that in the future they will improve this aspect.

Alternatives to TailwindCSS

Alternatives to TailwindCSS can be investigated such as twind and WindiCSS which are based on TailwindCSS but do not work as a PostCSS plugin.

Conclusion

WC is something different from a web, and therefore, you should use a framework that is specialized in the development of WebComponents. Also, the good practice would be to use ShadowDOM but that as we have already seen can give many problems and it is necessary to use some better alternative.

DEV Community: Max

Some tips for your first WebComponent

1. Attributes with basic types

2. Reactive vs static

3. Output with events

4. Working with styles

5. Use a template

Basic concepts about WebComponents

What is it?

How to generate WebComponents

Frameworks

Lit

Svelte

Stencil

Angular/Vue

Storybook

TS

Bundler

Adding styles to WebComponents

Style inheritance

Alternatives to TailwindCSS

Conclusion