vite-plugin-lit-css

2.2.2 verified Mon Apr 27 auth: no javascript

Vite plugin that transforms CSS/SCSS imports into Lit-compatible CSSResult or CSSResultGroup objects via constructible stylesheets. Current stable version is 2.2.2, released monthly. Designed exclusively for LitElement projects using Vite, it supports SASS/SCSS and PostCSS preprocessing. Unlike generic CSS handling, it outputs Lit template-literal stylesheets directly. Requires Lit 2/3 and Vite 5–7. TypeScript definitions included. Known limitation: HMR triggers full page reload.

Common errors

error Cannot find module 'vite-plugin-lit-css' or its corresponding type declarations. ↓

cause Missing dependency or wrong Node version (<18.2.0).

fix

Run 'npm install -D vite-plugin-lit-css' and ensure Node >=18.2.0.

error The request url failed: The request url failed with error code 404. Vite is not running. ↓

cause CommonJS require() used in an ESM-only package.

fix

Use 'import litCss from 'vite-plugin-lit-css'' instead of require().

error TypeScript: Property 'styles' does not exist on type 'typeof import('./styles.css')'. ↓

cause Missing or incorrect TypeScript type augmentation.

fix

Add '/// <reference types="vite-plugin-lit-css/client" />' before vite/client in your vite-env.d.ts.

Warnings

breaking vite-plugin-lit-css v2 drops support for Vite 4. Upgrade to Vite 5+. ↓

fix Update Vite to ^5.2.10 || ^6.0.0 || ^7.0.0

breaking vite-plugin-lit-css v2 requires Node.js >=18.2.0. ↓

fix Update Node.js to v18.2.0 or later.

gotcha HMR is not supported; every change triggers a full page reload. ↓

fix No workaround; consider using a different approach if HMR is critical.

gotcha Global stylesheets (e.g., index.css) must be excluded via the exclude option, otherwise they will be transformed into Lit styles incorrectly. ↓

fix Add global CSS files to the exclude option in the plugin configuration.

deprecated vite-plugin-lit-css 1.x (for Vite 4) is deprecated. ↓

fix Upgrade to v2 and migrate to Vite 5+.

Install

npm install vite-plugin-lit-css

yarn add vite-plugin-lit-css

pnpm add vite-plugin-lit-css

Imports

default

wrong

const litCss = require('vite-plugin-lit-css')

correct

import litCss from 'vite-plugin-lit-css'

ESM-only. CommonJS require will fail.

CSSResult
wrong
```
const styles = require('./styles.css')
```
correct
```
import styles from './styles.css'
```
Imports CSS as a Lit CSSResult object. Must be used in LitElement's static styles property.

TypeScript types

wrong

/// <reference types="vite/client" /> before vite-plugin-lit-css/client

correct

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

Type augmentation must be declared before vite/client types for proper CSS module declarations.

Quickstart

Shows how to configure the plugin with Vite and import a CSS file as a Lit stylesheet.

// vite.config.ts
import { defineConfig } from 'vite';
import litCss from 'vite-plugin-lit-css';

export default defineConfig({
  plugins: [
    litCss({
      exclude: ['./src/global.css'],
    }),
  ],
});

// src/my-element.ts
import { LitElement, html } from 'lit';
import styles from './styles.css';

export class MyElement extends LitElement {
  static styles = [styles];

  render() {
    return html`<p>Hello World</p>`;
  }
}

declare global {
  interface HTMLElementTagNameMap {
    'my-element': MyElement;
  }
}
customElements.define('my-element', MyElement);