esbuild-plugin-lit-css

4.1.1 verified Fri May 01 auth: no javascript

An esbuild plugin that allows importing CSS files as JavaScript tagged template literal objects, primarily for use with LitElement and similar libraries. Version 4.1.1 requires esbuild >=0.16.17 || ^0.25.0 and lit ^2.7.2 || ^3.0.0. It supports CSS preprocessing via a transform function, optional cssnano minification, and an inline mode that embeds CSS directly into JS/TS modules (at a performance cost). The plugin is part of the @pwrs/lit-css ecosystem, with parallel packages for rollup, Vite, webpack, TypeScript, and Parcel. Unlike alternatives that require separate build steps, this integrates directly into esbuild's build pipeline, making it seamless for Lit component development. It ships TypeScript types and is actively maintained with regular updates.

Common errors

error Error: The package "esbuild-plugin-lit-css" exports cannot be required() via CommonJS ↓

cause The package is ESM-only since v4.x; require() fails.

fix

Change to dynamic import: const { litCssPlugin } = await import('esbuild-plugin-lit-css'); or switch to ESM.

error TypeError: litCssPlugin is not a function ↓

cause Incorrect import syntax - using default import when expecting named export, or vice-versa.

fix

Ensure named import: import { litCssPlugin } from 'esbuild-plugin-lit-css'.

error Cannot find module '@pwrs/lit-css' ↓

cause Missing internal dependency; likely due to partial install or hoisting issue.

fix

Run npm install to ensure all dependencies are resolved.

Warnings

breaking v4.x requires esbuild >=0.16.17, breaking compatibility with older esbuild versions. ↓

fix Update esbuild to >=0.16.17 or use v3.x (if available).

breaking v4.x changed the default specifier from 'lit-element' to 'lit', requiring Lit v2.7.2+ or v3.0.0+. ↓

fix Set specifier: 'lit-element' in options if using older Lit packages.

gotcha The 'inline' option incurs a performance penalty because JS/TS files are parsed twice. ↓

fix Avoid inline mode for large projects; use separate modules for better performance.

deprecated The CommonJS require() pattern (require('esbuild-plugin-lit-css')) is unsupported since v4.x; ESM only. ↓

fix Use import { litCssPlugin } from 'esbuild-plugin-lit-css' instead.

gotcha If 'cssnano' is enabled, ensure cssnano is installed as a project dependency. ↓

fix Run npm install --save-dev cssnano.

Install

npm install esbuild-plugin-lit-css

yarn add esbuild-plugin-lit-css

pnpm add esbuild-plugin-lit-css

Imports

litCssPlugin

wrong

const litCssPlugin = require('esbuild-plugin-lit-css')

correct

import { litCssPlugin } from 'esbuild-plugin-lit-css'

ESM-only; no CommonJS export. Use dynamic import if needed.

toTaggedTemplateLiteral
```
import { toTaggedTemplateLiteral } from 'esbuild-plugin-lit-css'
```
Export since v4.1.0, for inline CSS transformation.

default import

wrong

import { default as litCssPlugin } from 'esbuild-plugin-lit-css'

correct

import litCssPlugin from 'esbuild-plugin-lit-css'

Default export is available but named export is preferred per docs.

Quickstart

Demonstrates basic setup of esbuild-plugin-lit-css with esbuild, importing CSS as Lit CSSResult.

import esbuild from 'esbuild';
import { litCssPlugin } from 'esbuild-plugin-lit-css';

await esbuild.build({
  entryPoints: ['src/main.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    litCssPlugin({
      filter: /\.css$/i,
      inline: false,
      cssnano: false,
      specifier: 'lit',
      tag: 'css',
      transform: (data, { filePath }) => data,
    }),
  ],
});

// Then in your Lit component files:
// import style from './my-styles.css'; // style is a CSSResult
// static styles = [style];