Registry / web-framework / esbuild-plugin-lit-css

esbuild-plugin-lit-css

library4.1.1jsnpmunverified

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.

web-framework

npm install esbuild-plugin-lit-css

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-LIT

esbuild-plugin-lit-css

web-frameworkjavascriptv4.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

litCssPlugin

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

✗ const litCssPlugin = require('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

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

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

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

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];

Debug

Known issues

breakingv4.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).

affects: <4.0.0

breakingv4.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.

affects: >=4.0.0

gotchaThe '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.

affects: >=4.1.0

deprecatedThe 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.

affects: >=4.0.0

gotchaIf 'cssnano' is enabled, ensure cssnano is installed as a project dependency.

fix

Run npm install --save-dev cssnano.

affects: >=1.0.0

Errors

Common errors & fixes

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

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.

TypeError: litCssPlugin is not a function

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

fix

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

Cannot find module '@pwrs/lit-css'

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

fix

Run npm install to ensure all dependencies are resolved.

Upgrade

Version history

4.1.1latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency: required to run as an esbuild plugin

litrequiredPeer dependency: provides the 'css' tagged template literal (or alternative specifier)

@pwrs/lit-cssrequiredInternal dependency for CSS transformation (version 4.x)

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/bennypowers/lit-css ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-lit-css ↗