{"id":25368,"library":"esbuild-plugin-lit-css","title":"esbuild-plugin-lit-css","description":"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.","status":"active","version":"4.1.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/bennypowers/lit-css","tags":["javascript","esbuild","plugin","lit","css","webcomponents","typescript"],"install":[{"cmd":"npm install esbuild-plugin-lit-css","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-lit-css","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-lit-css","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: required to run as an esbuild plugin","package":"esbuild","optional":false},{"reason":"Peer dependency: provides the 'css' tagged template literal (or alternative specifier)","package":"lit","optional":false},{"reason":"Internal dependency for CSS transformation (version 4.x)","package":"@pwrs/lit-css","optional":false}],"imports":[{"note":"ESM-only; no CommonJS export. Use dynamic import if needed.","wrong":"const litCssPlugin = require('esbuild-plugin-lit-css')","symbol":"litCssPlugin","correct":"import { litCssPlugin } from 'esbuild-plugin-lit-css'"},{"note":"Export since v4.1.0, for inline CSS transformation.","wrong":null,"symbol":"toTaggedTemplateLiteral","correct":"import { toTaggedTemplateLiteral } from 'esbuild-plugin-lit-css'"},{"note":"Default export is available but named export is preferred per docs.","wrong":"import { default as litCssPlugin } from 'esbuild-plugin-lit-css'","symbol":"default import","correct":"import litCssPlugin from 'esbuild-plugin-lit-css'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport { litCssPlugin } from 'esbuild-plugin-lit-css';\n\nawait esbuild.build({\n  entryPoints: ['src/main.ts'],\n  bundle: true,\n  outfile: 'dist/bundle.js',\n  plugins: [\n    litCssPlugin({\n      filter: /\\.css$/i,\n      inline: false,\n      cssnano: false,\n      specifier: 'lit',\n      tag: 'css',\n      transform: (data, { filePath }) => data,\n    }),\n  ],\n});\n\n// Then in your Lit component files:\n// import style from './my-styles.css'; // style is a CSSResult\n// static styles = [style];","lang":"typescript","description":"Demonstrates basic setup of esbuild-plugin-lit-css with esbuild, importing CSS as Lit CSSResult."},"warnings":[{"fix":"Update esbuild to >=0.16.17 or use v3.x (if available).","message":"v4.x requires esbuild >=0.16.17, breaking compatibility with older esbuild versions.","severity":"breaking","affected_versions":"<4.0.0"},{"fix":"Set specifier: 'lit-element' in options if using older Lit packages.","message":"v4.x changed the default specifier from 'lit-element' to 'lit', requiring Lit v2.7.2+ or v3.0.0+.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Avoid inline mode for large projects; use separate modules for better performance.","message":"The 'inline' option incurs a performance penalty because JS/TS files are parsed twice.","severity":"gotcha","affected_versions":">=4.1.0"},{"fix":"Use import { litCssPlugin } from 'esbuild-plugin-lit-css' instead.","message":"The CommonJS require() pattern (require('esbuild-plugin-lit-css')) is unsupported since v4.x; ESM only.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Run npm install --save-dev cssnano.","message":"If 'cssnano' is enabled, ensure cssnano is installed as a project dependency.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Change to dynamic import: const { litCssPlugin } = await import('esbuild-plugin-lit-css'); or switch to ESM.","cause":"The package is ESM-only since v4.x; require() fails.","error":"Error: The package \"esbuild-plugin-lit-css\" exports cannot be required() via CommonJS"},{"fix":"Ensure named import: import { litCssPlugin } from 'esbuild-plugin-lit-css'.","cause":"Incorrect import syntax - using default import when expecting named export, or vice-versa.","error":"TypeError: litCssPlugin is not a function"},{"fix":"Run npm install to ensure all dependencies are resolved.","cause":"Missing internal dependency; likely due to partial install or hoisting issue.","error":"Cannot find module '@pwrs/lit-css'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}