Create web components with typescript
Tags: webcomponents, typescript, webdev, rollup
Published: 2020-03-05 17:25:30

---
title: Create web components with typescript
published: true
description: Introducing my last project that allows you to start writing you web components with typescript in one minute (depending on your internet connection) and have ready for you all the needed functionalities.
tags: web-components, typescript, webdev, rollup
canonical_url: https://jesus.perezpaz.es/posts/web-components-generator-with-typescript/
---

In the last months, I've been digging in how to mix two of my favourites "technologies" of recent times. Web components and Typescript.

I understand web components as they are described in [their MDN page](https://developer.mozilla.org/en-US/docs/Web/Web_Components)

> Web Components is a suite of different technologies allowing you to create reusable custom elements — with their functionality encapsulated away from the rest of your code — and utilize them in your web apps.

So, in my opinion, they are not something that going to replace frameworks like React or Angular, but a way to create reusable pieces of code that you can use independently of your front-end stack.

In the other hand, I fell in love with [Typescript](https://www.typescriptlang.org/) since I started using it. The possibility to use the latest javascript and the security and bug prevention of the typing it's something I miss when I have to work in a project without it.

So, you will say, it's easy, start to write your components with typescript and then transpile and serve them...

and that's how my project started...

Soon in my project I wanted a way to serve my component as a single file, but separate my HTML and CSS in different files when developing, or use [lit-html](https://lit-html.polymer-project.org/) for the templates, and hot-reload when developing and an option to bundle everything to serve it in production... so I started to experiment with [webpack](https://webpack.js.org/) (and changed it later with [rollup](https://rollupjs.org/)).
I wanted as well a way to do tests, so I ended using [karma](https://karma-runner.github.io/) and [jasmine](https://jasmine.github.io/).
I wanted a way to have a component gallery, so I integrated [storybook](https://storybook.js.org/).
At the end I wanted to upload the result components to npm, so needed to create a package.json and a README.

And all that is what included out of the box in what I've called "[wc-base-typescript](https://github.com/tx2z/wc-base-typescript)" (Original, I know :)).

This project allows you to start writing you web components with typescript in one minute (depending on your internet connection) and have ready for you all the functionalities I described above.

Do you want to test it or use it in your next web-component projects? Keep reading or go directly to the [wc-base-typescript github repository](https://github.com/tx2z/wc-base-typescript) as it's more or less the same but with fewer words.

Of course, don't forget to give the project an star in github if you think it deserves it!

And if there is something you think can be done in any other (or better) way, don't hesitate to tell me in the comments or send me a PR, collaboration is more than welcome :)

Ready? Let's go!

## Getting started

First thing. It's better if you copy the repository and make your own for your project. You can always download the code but I recommend to use [degit](https://github.com/Rich-Harris/degit/) or any similar tool for convenience.

``` bash
npm install -g degit #In case you don't have it installed
degit tx2z/wc-base-typescript
```

Once the project is on your computer, enter the folder and install all npm dependencies:

``` bash
npm i
```

And you can start to write your components! I told you 1 minute :)

All the components you're going to create will be stored in *src/components*.

I've created in the project three components to show the different options available:

* The **base-component** generates a web component with no dependencies or libraries.

* The **lithtml-component** generate a web component using [lit-html](https://lit-html.polymer-project.org/) as template library.

* The **noshadow-component** generate a custom element (not sure if it can be called a web component) without using the shadow DOM & with no dependencies or libraries.

For a quick start, you can copy the content of one of the example components and change what you need.

It's important as well to include your defined custom element in *public/index.html* so you can test it while developing. If you open it you will see that I've included the three example components there.

Then, to run a server in development mode you only have to type in your terminal:

``` bash
npm start
```

Rollup will transpile and pack your components and reload the page every time you save a file.

That's it. Nothing to configure or to do other than focus in your code!

## Tests

So maybe you want to add some test to your components to avoid problems when the code-base start to grow... or, even better, you're a super-developer that like to write your code following the Test-driven development (TDD) process.

I had some hard time trying to add test to my previous web component projects, but, again, now everything is pre-configured and works out of the box. [Karma](https://karma-runner.github.io/) & [jasmine](https://jasmine.github.io/) are included as testing environment and framework.

Inside your component folder include a file ending with "**spec.ts**" and write your tests (with typescript). Of course, there are some examples in the example components.

By default, launchers for chrome and firefox are already installed and configured (your test will be launched in both browsers) but you can install and use any other [karma-launcher](https://www.npmjs.com/search?q=keywords:karma-launcher) if you want.

To execute the test use:

``` bash
npm test
```

Karma has as well live-reload, so if you change your components or test files the test will be executed again.

## Using Storybook as component gallery

You can optionally use [storybook](https://storybook.js.org/) to develop, document and create a gallery for your web components. You can learn more about storybook in their [documentation site](https://storybook.js.org/docs/basics/introduction/).

Just a little warning here, storybook uses webpack and, when building, rollup will be used... the result should act and look the same but it's not exactly the same.

Storybook for HTML is used and tuned so no further configuration is needed to use it for your components. The following storybook addons are included:

* [Knobs](https://github.com/storybookjs/storybook/tree/master/addons/knobs): Allows edit web components' props dynamically using the Storybook UI.

* [Viewport](https://github.com/storybookjs/storybook/tree/master/addons/viewport): Allows web components to be displayed in different sizes and layouts in Storybook. This helps build responsive web components inside of Storybook.

* [A11y](https://github.com/storybookjs/storybook/tree/master/addons/a11y): Helps to make your web components more accessible.

* [Notes](https://github.com/storybookjs/storybook/tree/master/addons/notes): Allows to write notes or documentation for your web components.

This is a standard storybook installation. You can add other [addons](https://github.com/storybookjs/storybook/tree/master/addons/) or configurations that suit your needs.

### Create stories

There are two files inside the example components that are used by storybook.

* **@component.stories.ts**: Is the file to create a story for your component. You can check storybook documentation about how to create stories starting [here](https://storybook.js.org/docs/guides/guide-html/#step-4-write-your-stories)

* **README.md**: It's used to add documentation for your component using the [Notes](https://github.com/storybookjs/storybook/tree/master/addons/notes) storybook addon.

Storybook will use these two files to generate the stories and the documentation. Once these two files are present run storybook with:

``` bash
npm run storybook
```

Again, examples of all this can be found in the example components provided :)

To build a static storybook app ready to be deployed run:

``` bash
npm run storybook-build
```

You can find your storybook builds in the "dist-storybook" folder.

If you want to publish your storybook in github pages I recommend you to install [storybook-deployer](https://github.com/storybookjs/storybook-deployer). It will do all the work for you.

Note that storybook is completely optional. If you're not using it you can remove (or not create) the @component.stories.ts files. Even you can remove all the storybook and webpack references in the [package.json](package.json) to completely remove storybook from your project.

## Build the components

So it's time to build your components to use them elsewhere. Fear not, just run:

``` bash
npm run build
```

You can find your builds in the "dist" folder.

Your components will be compiled as js file (as [ES module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)), to use them as modules in your application, and in a dist.js (as [iife](https://developer.mozilla.org/en-US/docs/Glossary/IIFE)), to use them directly in browsers, with the same name you give to the folder in *src/components*.

All modules will include their respective [Typescript declaration files](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html) in case you or others want to use them with typescript.

The [webcomponents polyfills](https://github.com/webcomponents/polyfills) will be included as well in the "dist" folder, you can use them or load directly the code from a CDN such as unpkg: <https://unpkg.com/@webcomponents/webcomponentsjs@^2/>

So that's it take your components and use them whatever you want. Just copy-paste the version (ES module or IIFE) that you need in your project and use it.

...

No, that's not how things work nowadays, I know. The wc-base-typescript simplify as well all you need to...

## Publish component to NPM

You may have seen that a **README** and a **"package.json"** are included as well in every example component folder. Rollup will copy these files to the "dist" folder and add some important info to the package.json.

In other words, you don't need to worry about the *main*, *module* or *type* properties, as they will be filled automatically, but you need to provide the rest of the information in the package.json.

All you need to do to publish your component in NPM is to enter the component folder inside "dist" your terminal and:

``` bash
npm publish
```

Of course, you need to have an account in npm and login into it in your terminal before that. I recommend reading the [how-to](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) in the npm docs before publishing a package.

Once your package is in npm it can be installed and used as any other npm package. The ES module version will be the default.

## Closing up

So with the [wc-base-typescript](https://github.com/tx2z/wc-base-typescript) project you can quickly create, test and build for production and publish web components, and optionally create a components gallery to show them up.

If you want to see one of the uses I give it to it you can check my [Creative Commons license generator as web component](https://www.npmjs.com/package/creative-commons-web-component) with his [galery](https://tx2z.github.io/creativecommons-webcomponent/) and [repository](https://github.com/tx2z/creativecommons-webcomponent). I created it (all included) in around 6 hours of intermittent work.

What do you think? Can it be useful for you?

PD: Don't hesitate to tell me if you use it for any of your projects, I will love to know about what are you creating with it :)
PD2: And again, if there is something you think can be done in any other (or better) way, don't hesitate to tell me in the comments or send me a PR :D