Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 38 ยท Getting Started

Lit Setup, CDN and Tooling

Choose how to run Lit: a CDN import, an import map, or npm with Vite. Learn the project layout, TypeScript decorator settings, editor tooling and dev versus production builds.

One of Lit's best qualities is that it does not force a toolchain on you. A Lit component is a JavaScript module, and browsers load modules natively. You can start with a single HTML file and grow into a full build pipeline only when your project needs one. This lesson shows the four common setups, when each makes sense, and which tools help you write components faster.

Option 1: import from a CDN

The fastest way to experiment is a direct URL import. Every live example in this track uses it:

HTML
<script type="module">
  import { LitElement, html, css } from "https://cdn.jsdelivr.net/gh/lit/[email protected]/all/lit-all.min.js";
</script>

The lit-all file bundles lit, all directives and the other core pieces into one request. Two things to know:

  • Always pin a version (@3.3.1). An unpinned URL can change under you.
  • The bundle prints a console warning suggesting the npm package. That is harmless; it is only a reminder that a build tool can remove unused code.

If you only need the essentials, lit-core.min.js in the same folder is about half the size and leaves out the extras. This option is good for prototypes, documentation pages and tiny widgets. It is a poor fit for large apps, because there is no tree shaking and no offline support.

Option 2: import maps

An import map lets you write the same bare import (from "lit") you would use with npm, while the browser resolves it to a URL. This is handy because your component code is then identical in the prototype and the production build.

Bare imports with an import map

The import map must appear before the first module script that uses it. Because the code says from "lit", moving to npm later changes nothing in your component files.

Option 3: npm with Vite

For real applications, install Lit and use a bundler. Vite is the usual choice because it needs almost no configuration. These commands are for your own computer, so they are shown as read-only code:

Terminal
npm create vite@latest my-lit-app -- --template lit
cd my-lit-app
npm install
npm run dev

Use --template lit-ts if you want TypeScript. The generated project looks like this:

TEXT
my-lit-app/
  index.html          page that loads the component
  package.json        dependencies: lit, vite
  src/
    my-element.js     your first component
    index.css

If you would rather add Lit to an existing project, install it directly:

Terminal
npm install lit

Then import from the package name. The modules you will use most are:

JavaScript
import { LitElement, html, css, nothing } from "lit";
import { classMap } from "lit/directives/class-map.js";
import { property, state, customElement } from "lit/decorators.js";

Vite bundles only what you import, so unused directives never reach the browser. Build for production with npm run build; the result is static files that any web server can deliver.

Option 4: a no-bundler dev server

Open Web Components (open-wc) offers @web/dev-server, a server that serves your files unbundled and resolves bare imports for you. It is a good middle path: you write standard modules, reload instantly, and run tests with @web/test-runner (covered in the Testing and Tooling chapter). The generator is:

Terminal
npm init @open-wc

Which option should I pick?

Situation Setup
Learning, demos, quick experiments CDN import or import map
Component library for others to install npm, Vite or Rollup in library mode
Full application npm with Vite (or your framework's own tooling)
Adding one widget to an existing server-rendered site Pre-built bundle loaded with <script type="module">

TypeScript and decorators

Lit works with TypeScript and with plain JavaScript. If you use decorators (@property, @customElement), check your compiler settings. For the long-established "experimental" decorators the tsconfig.json needs:

JSON
{
  "compilerOptions": {
    "target": "ES2022",
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
    "moduleResolution": "bundler"
  }
}

useDefineForClassFields: false matters. With it on, a class field such as name = "x" is defined on the instance and hides the accessor that Lit creates for reactive properties, so updates silently stop working. Lit 3 also supports the newer standard decorators; with those you add the accessor keyword. If decorators feel like too much setup, static properties works everywhere with no compiler flags at all.

Check the version that is loaded

When something behaves oddly, first confirm which Lit version the page actually loaded. Lit records its version on globalThis, which is also how Lit warns you if two copies are loaded together.

Which Lit is running?

If an array contains more than one version, two copies of Lit are on the page. That can cause confusing bugs, for example a template created by one copy rendering badly in the other. Fix it by making your dependencies share one version.

Dev mode versus production

Lit ships two builds. The development build prints helpful warnings, for example when a reactive property is changed during updated, or when a class field shadows an accessor. The production build removes those checks to be smaller and faster. With Vite, npm run dev uses the development build and npm run build uses production. Importing the CDN bundle gives you the production build, which is why mistakes are quieter there.

Editor support

  • lit-plugin for VS Code (and the lit-analyzer CLI) checks templates: unknown element names, wrong attribute types, missing imports.
  • Prettier formats html templates inside JavaScript. Enable its embedded-language formatting.
  • custom-elements.json is a machine-readable description of your components, produced by the Custom Elements Manifest analyzer. Editors and documentation tools such as Storybook read it.
flowchart LR
  A["Write components<br/>(.js or .ts)"] --> B["Dev server<br/>(Vite / web-dev-server)"]
  B --> C["Test<br/>(web-test-runner)"]
  C --> D["Build<br/>(Vite / Rollup)"]
  D --> E["Publish to npm<br/>or deploy static files"]

A typical Lit workflow from editor to deployment.

Never include two different Lit versions in the same page. Pin one version in every import, and if you publish a component library, list lit as a peer dependency so that applications provide the single copy.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should CDN imports include a version number?

    Pinning, for example @3.3.1, makes the loaded code reproducible.
  2. 2. What does an import map allow you to write?

    The map tells the browser which URL a bare module name points to.
  3. 3. Which TypeScript setting prevents class fields from shadowing Lit's reactive accessors (for experimental decorators)?

    With useDefineForClassFields on, fields are defined on instances and hide the accessors Lit creates.
  4. 4. What does it usually mean if globalThis.litHtmlVersions has two entries?

    Each loaded copy registers its version; two entries signal duplicated Lit code.

Summary

  • Lit runs from a CDN URL, an import map, npm with Vite, or an unbundled dev server such as @web/dev-server.
  • Pin versions, and make sure only one copy of Lit is on the page.
  • Import maps keep bare from "lit" imports identical across prototype and production.
  • For TypeScript decorators, set experimentalDecorators and useDefineForClassFields: false.
  • Dev builds warn about mistakes; production builds are smaller and quieter.

Next: Custom Elements: The Basics