Hero Image

a dive into lit with openwc (part 1): your quickstart into lit

This blog post is part of a serie of webinars and talks, supported by blog posts, which will be an overview of my journey as a front-end developer in discovering and learning about Lit-html. From getting to know what lit-HTML is all about, to programming some more advanced techniques for your Web Components and building some Front-end Generators in lit-HTML to make your life a lot easier.

For now I divided this journey into three parts:

  • A dive into lit-HTML with open-wc (part 1) - Your quickstart into Lit
  • A dive into lit-HTML with open-wc (part 2) - Building with Lit in the 21st-century
  • A dive into lit-HTML with open-wc (part 3) - Front-end generators with Lit

Matthijs Vliegenthart - A dive into lit-HTML with open-wc (part 1) - Your quickstart into Lit



In 2017 Google announced lit-HTML, a library from Polymer for building Web Components. Nowadays Lit has extended itself in being its own platform and Google even says that it's THE future for building Web Components for the web. They have some great documentation of lit-HTML and why you should use it, so I will give you a short summary of that and put some sources beneath it for you to dive deeper into.

Lit is a combination of lit-HTML and LitElement. For now we will focus on lit-HTML, because LitElement is just a base class that will help us to use the functionality of lit-HTML in our code easily.

Lit-HTML is an efficient, expressive, extensible HTML templating library for Javascript. It is fast and works great for modern browsers.


Lit-HTML announced at Polymer Summit 2017: https://www.youtube.com/watch?v=ruql541T7gc&feature=emb_logo

Lit-HTML and documentation: https://lit-html.polymer-project.org/

Lit-HTML vs. React (Preact): hhttps://codeburst.io/a-night-experimenting-with-lit-html-585a8c69892a


To show you the difference between all the JavaScript frameworks we know, like Angular, React, etc. and lit-HTML we must look at the way they manipulate HTML inside our DOM.

First we had DOM-manipulation in plain JavaScript, which uses a lot of code and nowadays seems a bit overkill.

1 Fig. 1: DOM-manipulation in JavaScript

Then we had DOM-manipulation in jQuery, which was just an easier way to use DOM-manipulation in JavaScript. The problem here is that your state management is still the DOM itself and there was no other way to change the existing DOM than to do it manually.

2 Fig. 2: DOM-manipulation in jQuery

Frameworks like Angular found a way to solve this problem by using Embedded Expression inside their HTML-like code to manipulate the DOM in a dynamic way.

3 Fig. 3: DOM-manipulation with Embedded Expressions (Angular)

And frameworks like React and Preact use JSX (a HTML-like syntax within Javascript) to change a virtual DOM, which then checks the DOM-nodes that are changed and will only update those nodes inside the current DOM.

4-nieuw Fig. 4: DOM-manipulation with JSX and vDOM (React)

But what about lit-HTML? Why is it so different from all these other Javascript Frameworks and why should we use it? The answer is: “Tagged Template Literals”.

Tagged Template Literals

For DOM-manipulation lit-HTML uses Tagged Template Literals. A way of defining some DOM-elements which is native to all of the modern browsers we know today.

What are they?

Tagged template literals look like this:

5 Fig. 5: A template tag literal

The main part of the Tagged Template Literal is the Template Literal. Template Literals are basically just strings, surrounded by backticks:

6 Fig. 6: String with backticks

Because they are surrounded by backticks, they can span multiple lines if you want to. This comes in handy for coding HTML-like syntaxes.

7 Fig. 7: Can span multiple lines

Now we can make things dynamic inside our Template Literals with Embedded JavaScript Expressions, as we do in Angular:

8 Fig. 8: They can contain Embedded JS expressions

The magic happens when we can tag those Template Literals. Tagging them basically is running the string within the backticks through a function. In this case, and in most cases within lit-HTML, this is the HTML function, which is defined in lit-HTML.

9 Fig. 9: They can be tagged

How do they work?

Now that’s great and all, but how does that work? How does lit-HTML know what to do with the string and what the dynamic parts are?

Lit-HTML replaces the dynamic Embedded Expressions inside your Template Literal with placeholders:

10 Fig. 10: lit-HTML replaces the expressions with placeholders

It then defines a template-tag, surrounding the content you placed within the backticks of your Template Literal. This template-tag is native to a modern browsers:

11 Fig. 11: defining a template-tag.

Lit-HTML remembers the exact location of these placeholders. Lit-HTML calls these locations where the placeholders where “parts”:

12 Fig. 12: remembering the “parts”.

And now we can set any content we want to these specific parts:

13 Fig. 13: set data dynamically to “parts”.

Why should we use them?

That sounds great, but why should we do that? What makes Tagged Template Literals better than for example using just Embedded Expressions or JSX? Google says, lit-HTML is efficient, expressive and extensible:

Efficient: Lit-HTML will only render the dynamic “parts” again if something changes in your data. For example, React will replace the whole DOM-element when it detects a difference between the virtual DOM and the current DOM. This way less code will be re-rendered everytime your data changes and it will save rendering cost.

Expressive: All the functions we know and love from frameworks like Angular and React we can use in lit-HTML, like expressions, value attributes, using arrays and iterables within your html-like syntax and we can even use Promises to render content based on certain circumstances. A bonus in lit-HTML is we can create dom nodes and set them to dynamic parts and we can nest these Tagged Template Literals dynamically.

Extensible: Lit-HTML is set up in a way that it is really easy to extend the code of lit-HTML with directives. These directives give you a custom way to handle values in lit-HTML and make this framework really dynamic on itself.

And it is all just JavaScript! Which means we can also use TypeScript!

A small bonus is that the source code of lit-HTML is even smaller than just 2 kilobytes. Maybe not that relevant today, where frameworks are getting smaller and smaller and build engines are getting better and better in compressing our code, but still….


Now that I knew what lit-HTML was and why I should use it, I tried to find a good entry point for myself to start developing in lit-HTML and I stumbled across open-wc. In their own words, open-wc is a platform to empower everyone with a powerful and battle-tested setup to start building and sharing Web Components. And it was exactly what I was looking for: https://open-wc.org/

Underneath this chapter I will give you some entry points on the open-wc website to provide you a headstart for this, but for the next chapter I would really like to focus on explaining the whole development cycle, so you can start to develop some well coded, tested and optimized Applications and Web Component in lit-HTML.

Code examples

Open-wc has a series of examples how to code certain things in lit-HTML. This comes in handy if you just started developing in lit-HTML and want to know for example how to handle properties, render you Template Literals and fetching data. If you want to read more about these examples, go visit https://open-wc.org/developing/code-examples.html.


A handy thing about open-wc is that they express their opinions on what they think you should use in certain situations or they will give you an overview of what options you have for certain techniques. For example routing, where they have an overview of a number of projects with good routers for lit-HTML, each with their usage stats and GitHub start, so you can make a well thought decision. If you want to read more about routing in lit-HTML, go to https://open-wc.org/developing/routing.html.


They even have some tips for you to choose the best IDE for developing in lit-HTML or make sure you have the correct plugins for the IDE you use on a daily basis. I use, for example, IntelliJ products like PhPStorm and WebStorm a lot and they have some good documentation for that to make this a great IDE to develop in lit-HTML. Or they navigate you to the correct urls on the JetBrains website.

I really encourage you to start reading the topics on this site you find interesting or useful for building your Web Components. It is a really nice collection of important things you should know before you publish your perfectly coded, tested and optimized Web Component!

Development Cycle

Open-wc.org has some great documentation on developing, testing and building your own applications and Web Components. For each of these development stages they recommend some techniques they think are suitable for developing in lit-HTML.

In this chapter I will give you a short overview of the development stages and how open-wc.org recommends you to develop. I built a small test application so you can code along and test these development stages for yourself.

Development - Scaffolding

The best thing, in my opinion, about open-wc.org is that they provide a npm command that will scaffold a starterproject for you. The only thing you’ll need to do is:

npm init @open-wc

  1. The first thing it will ask you ‘what would you like to do today’, in which you are given 2 options:
  • Scaffold a new project: to get a clean starterproject.

  • Upgrade an existing project: to start using lit-HTML in an existing project or upgrade you existing lit-HTML project with one of the next options.

For this project I choose to scaffold a new project

  1. Next it will ask you if you like to scaffold a Web Component or an Application. They are both good entry points for your Application or Web Component, but have some small differences in file setup and features. I choose to scaffold a Web Component.

  2. Then it will give you some options for you to add to your project. You can choose to add these options or leave them, according to your needs.

  • Linting (Eslint & Prettier)

  • Testing (Karma)

  • Demoing (Storybook)

For this demo I only added the linting and testing option. The Storybook option I might add in a later stage.

  1. And at last it will ask you the name of your Application or Web Component. This name will also be the name of the folder it creates in which your project is setup, so you don’t need to create a folder in advance. And that’s it! Now you are ready to go and start developing your Web Component in lit-HTML.

Dev server

The open-wc scaffolded project includes a decent development server for you to run your application on in development mode, the es-dev-server. The command to run you app is:

npm run start

It will run your Application or Web Component on https://localhost:8000. It also runs in watch-mode, so everytime you update your code, the page will refresh and you will see your updated code in the browser.

If you want to read more about the es-dev-server, go to https://open-wc.org/developing/es-dev-server.html.


The open-wc scaffolded project has some pretty aggressive linting. And that’s a good thing, because not every IDE knows how to handle these Tagged Template Literals with a HTML-like syntax very well. The linting consist out of 2 parts, the linting and the formatting:

npm run lint

This command does an audit based on the code in your project and the linting settings of the project. It will fail when your code does not comply to the rules of the linting setup and it will give the exact file, rule number and reason it failed there.

npm run format

The format command will format your code based on the linting setup of your project. This does a pretty great job in formatting your Tagged Template Literals. Especially PhPStorm, which I’m using, does a bad job in formatting them, but the formatting fixes all of that!

If you want to read more about linting in lit-HTML, go to https://open-wc.org/linting/.

Testing - Unit Testing

The fun thing about lit-HTML being just JavaScript is that you can choose any test-framework you like. Open-wc recommends Karma as a general-purpose tool for testing because it can run in a large number of browsers. That way you know your code works, even in IE11!

If you want to read more about testing with Karma, go to https://open-wc.org/testing/testing-karma.html.

Or visit the official Karma documentation on https://karma-runner.github.io/latest/index.html.


If you really want to know if your code runs in a large number of browsers quickly and you want to automate that, browserstack has a really nice feature to do this. All you have to do is connect your project to your browserstack account, add some configuration and run a command. It will then run all your Karma tests in the all the browsers you defined and give you a short review about that:

14 Fig. 14: result of testing Karma in Browserstack

By clicking those links with the “launcher.browserstack tag”, you are navigated to an overview of your test, including a video of the screen you would normally see with a Karma test, but then in that specific browser. In that way you can automate a lot of tests really quick and it is a powerful tool for testing your Application or Web Component.

15 Fig. 15: Test result in browserstack

If you want to read more about testing Karma in multiple browsers with Browserstack, go to https://open-wc.org/testing/testing-karma-bs.html.


The final step before we can publish our Application or Web Component is to build our project. For this step open-wc recommends you to use Rollup, for it optimizes your code for production and ensures it runs on all supported browsers. All you need to do is run the following command:

npm run build or npm run start:build. (The last command will run your project in production mode)

It will create a dist folder inside your project with the optimized code for you to publish. It even creates a service worker for you, which is not working out of the box, to start turning your project into a Progressive Web Application.

If you want to read more about building your app with Rollup, go to https://open-wc.org/building/building-rollup.html.