Installation

Install the plugin, add one line to vite.config.ts, and register the ambient types. If you have never used the plugin, follow the tutorial instead; it includes these steps.

Install

npm

npm i -D @oddsquad/vite-plugin-lit

pnpm

pnpm add -D @oddsquad/vite-plugin-lit

yarn

yarn add -D @oddsquad/vite-plugin-lit

bun

bun add -d @oddsquad/vite-plugin-lit

Lit and Vite stay your dependencies. Compatibility lists the versions each release supports and the one dev mode it does not.

Add it to Vite

Add litPlugin() to the plugins array. Nothing else moves.

vite.config.ts

import {defineConfig} from 'vite';
import {litPlugin} from '@oddsquad/vite-plugin-lit';

export default defineConfig({
  plugins: [litPlugin()],
});

Hot patching, the on-page indicator and the CSS import queries are on from here. The DevTools timeline and the source overlay are opt-in; the options reference has the switches.

The patching applies to the dev server only, so a production build is untouched. The ?css-sheet and ?hmr-url queries resolve in dev and build alike.

Add the types

The import queries ship ambient declarations in @oddsquad/vite-plugin-lit/client. Without them TypeScript cannot type import sheet from './theme.css?css-sheet'.

The types array replaces TypeScript’s default, so list vite/client next to it rather than instead of it. The rest of this file is the lit-ts template’s, unchanged.

tsconfig.json

{
  "compilerOptions": {
    "target": "es2023",
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
    "module": "esnext",
    "lib": ["ES2023", "DOM"],
    "types": ["vite/client", "@oddsquad/vite-plugin-lit/client"],
    "allowArbitraryExtensions": true,
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "moduleDetection": "force",
    "noEmit": true,

    /* Linting */
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "erasableSyntaxOnly": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"]
}

One .d.ts anywhere in your include does the same job, if you would rather not touch types:

src/lit-plugin.d.ts

/// <reference types="@oddsquad/vite-plugin-lit/client" />

Check it works

Start the dev server and open a page that renders a Lit component.

npm run dev

A small indicator sits in the corner of the page. It is idle until an update arrives.

Type into an input inside a component, then edit that component’s template and save. The markup changes, what you typed stays, and the indicator pulses green. That is a hot patch: an edit applied to the running page without a reload.

If the page reloads instead, the edit hit a shape that cannot be patched in place. Limitations names each one.

Related

OptionsEvery option litPlugin() takes, with defaults.

Keep state across editsWhat a hot patch preserves, and the three settings worth changing.