SetupPermalink to “Setup”
The simplest way to add lit-html to a project is to install it from the npm registry.
If you're starting a brand-new project, run the following command in your project area to set up npm:
Respond to the prompts to set up your project. You can hit return to accept the default values.
If you're working on a project with many front-end dependencies, you may want to use the npm
dedupecommand to try and reduce duplicated modules:
DevelopmentPermalink to “Development”
During the development phase, you might want the following tools:
- IDE plugins, for linting and code highlighting.
- Linter plugins, for checking lit-html templates.
- A dev server, for previewing code without a build step.
IDE pluginsPermalink to “IDE plugins”
The following VS Code and TypeScript plugins check lit-html templates for errors:
The awesome-lit-html repo lists other IDE plugins.
LintingPermalink to “Linting”
ESLint is recommended for linting lit-html code. The following ESLint plugin can be added to check for some common issues in lit-html templates:
Another alternative is to use the
lit-analyzer CLI alongside ESLint to detect issues in your lit-html templates:
lit-analyzer uses the same backend as the VS Code and TypeScript plugins listed in IDE plugins.
Dev serverPermalink to “Dev server”
To run in the browser, the bare identifier ('lit-html') needs to be transformed to a path or URL that the browser can load (such as '/node_modules/lit-html/lit-html.js'). ES dev server is an open-source dev server that handles this and other transforms.
You can also use the Polymer CLI dev server, if you already have it installed. For new projects, we recommend the ES dev server.
If you already have a dev server that integrates with your build process, you can use that, instead.
ES Dev Server
Install ES dev server:
Add a command to your
Run the dev server:
For full installation and usage instructions, see the open-wc website.
TestingPermalink to “Testing”
Web Component Tester (WCT) is an end-to-end testing environment that supports node-style module specifiers. works with the Mocha testing framework and (optionally) the Chai assertion library. There are two ways to add WCT to your project:
- web-component-tester. Installing the full WCT package gives you Mocha and Chai, as well as some other add-ons.
- wct-mocha. Just the WCT client-side library. You'll need to install your own version of Mocha, and any other add-ons you want.
Alternately, you can also use the Karma test runner. The Open Web Components recommendations includes a Karma setup that resolves module dependencies by bundling with webpack before running tests.
BuildPermalink to “Build”
Build tools take your code and make it production-ready. Among the things you may need build tools to do:
- Bundle modules together to improve performance by reducing the number of files that need to be transferred.
- Add required polyfills (may be done manually).
Many build tools can do this for you. Currently we recommend Rollup, and provide a sample project using Rollup.
If you're using another tool or creating your own Rollup configuration, see the section on Build considerations.
For more details on the build steps, see the LitElement Build for production guide. lit-html has the same requirements as LitElement, except that lit-html requires only the Template polyfill, not the full Web Components polyfills.
Build your project with RollupPermalink to “Build your project with Rollup”
Rollup works well with lit-html. The lit-html-build repository is a simple example project using lit-html with a Rollup build.
For more information on the build steps, see the LitElement Build for production guide.
open-wc also has Rollup build resources.
Build your project with webpackPermalink to “Build your project with webpack”
webpack is a powerful build tool with a large ecosystem of plugins.
See the open-wc default webpack configuration provides a great starting point for building projects that use lit-html. See their webpack page for instructions on getting started.
Build considerationsPermalink to “Build considerations ”
If you're creating your own configuration for webpack, Rollup, or another tool, here are some factors to consider:
- ES6 to ES5 compilation.
- lit-html template minification.
For more details on these considerations, see the LitElement Build for production guide. lit-html has the same requirements as LitElement, except that lit-html requires only the Template polyfill, not the full Web Components polyfills.
Compilation and module transform
To support legacy browsers, your build tools need to compile ES6 features to ES5. In general, ES6 is faster than the ES5 equivalent, so try to serve ES6 to browsers that support it.
If you're working in TypeScript, the TypeScript compiler,
For example, if you have a
As part of the build process, you'll probably want to minify the HTML templates. Most HTML minifiers don't support HTML inside template literals, as used by lit-html, so you'll need to use a build plugin that supports minifying lit-html templates. Minifying lit-html templates can improve performance by reducing the number of nodes in a template.
- Babel plugin. For build chains that use Babel for compilation. The open-wc webpack default configuration uses this plugin.
- Rollup plugin. If you're building your own Rollup configuration.
To run on Internet Explorer 11, which doesn't support the
<template> element, you'll need a polyfill. You can use the template polyfill included with the Web Components polyfills.
Install the template polyfill:
Use the template polyfill:
Note: when transpiling for IE11, the Babel polyfills need to be bundled separately from the application code, and loaded before the template polyfill. This is demonstrated in the
index-prod.html file in the Rollup sample project.