Lit Setup

Ways to Start a Lit Project

There are three common ways to start using Lit: adding the lit package to an existing bundler-based project, scaffolding a new project with the official Lit starter templates, or loading Lit directly from a CDN via native ES modules for a no-build prototype.

For real applications, a bundler-based setup (Vite is the most common choice today) is recommended because it gives you fast rebuilds, TypeScript support, and optimized production output.

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

Vite's official lit-ts template scaffolds a working TypeScript + Lit project with decorators already configured.

Installing Lit into an Existing Project

npm install lit

# TypeScript projects also need:
npm install -D typescript

• lit is the only runtime dependency required to author components.
• TypeScript is optional but strongly recommended for the @property, @state, and @customElement decorators.
• No Lit-specific CLI is required — any bundler (Vite, esbuild, Rollup, webpack) works.
• For quick experiments, Lit can be imported directly from a CDN like https://cdn.jsdelivr.net/npm/lit@3/index.js.

Setup Cheat Sheet

Commands and configuration you'll reach for when starting a project.

Configuring tsconfig.json for Decorators

Lit's decorators (@customElement, @property, @state, and others) rely on the TypeScript experimentalDecorators compiler option. You also typically want useDefineForClassFields set to false so class fields are assigned with = rather than defined with Object.defineProperty, which can otherwise override Lit's own reactive property accessors.

{
  "compilerOptions": {
    "target": "ES2021",
    "module": "ESNext",
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
    "moduleResolution": "bundler"
  }
}

This is the same configuration the official lit-ts Vite template ships with.

A No-Build Prototype Setup

For quick demos or learning, you can skip a build tool entirely by importing Lit as a native ES module from a CDN and writing plain JavaScript (no decorators, since browsers don't support them natively).

<script type="module">
  import { LitElement, html } from 'https://cdn.jsdelivr.net/npm/lit@3/index.js';

  class HelloWorld extends LitElement {
    render() {
      return html`<p>Hello from a script tag!</p>`;
    }
  }
  customElements.define('hello-world', HelloWorld);
</script>

<hello-world></hello-world>

Common Mistakes

• Forgetting experimentalDecorators: true, which causes decorator syntax errors when compiling TypeScript.
• Leaving useDefineForClassFields at its default true in a decorator-based project, which can silently break reactive properties.
• Assuming a bundler is mandatory — Lit runs fine with native ES modules for small projects or demos.
• Installing an old Lit 1.x/2.x tutorial's dependencies (lit-element, lit-html as separate packages) instead of the unified lit package used in Lit 3.

Key Takeaways

• The fastest way to start a real project is npm create vite@latest app -- --template lit-ts.
• TypeScript decorators require experimentalDecorators: true and usually useDefineForClassFields: false.
• Lit can run without any build tool via native ES modules, which is useful for prototypes.
• Modern Lit 3 projects should install the single lit package rather than legacy separate packages.