An esbuild plugin to transform a Lit component styles via Lightning CSS: an extremely fast CSS parser, bundler, transformer, and minifier.
Lightning CSS is a tool written in Rust that empowers developers to use modern CSS features and future syntax today. It offers the following syntax transformations:
- :dir() Selector
- :is() Selector
- :not() Selector
- Color function
- Color mix
- Custom media queries
- Double position gradients
- Hex colors with alpha
- HWB colors
- Lab colors
- Logical properties
- Math functions
- Media query ranges
- Nesting
- Relative colors
- system-ui font
Furthermore, Lightning CSS offers a range of built-in features, including:
- Conditional imports
- Vendor prefixing (an Autoprefixer alternative)
- Optimizazions and minification (a CSSNano alternative)
- Shorthands
The plugin will process the styles and return them as a JavaScript/TypeScript string, giving you a versatile way to deal with them.
-
Install the NPM package of the plugin, along with esbuild itself:
pnpm add -D @detra-lab/esbuild-plugin-lit-css esbuild
-
Add the plugin to your esbuild configuration:
// ./esbuild.js import { litCssPlugin } from '@detra-lab/esbuild-plugin-lit-css' // You can also use the default export if you prefer: // import litCssPlugin from '@detra-lab/esbuild-plugin-lit-css' await esbuild.build({ // Other esbuild options... plugins: [litCssPlugin()] })
-
Import the CSS within the file that hosts the Lit component. If you encounter type issues with CSS file imports, check out the TypeScript section.
// ./src/components/hello-world.ts import { html, LitElement } from 'lit' import { customElement, property } from 'lit/decorators.js' import css from './styles.css' @customElement('hello-world') export class SampleElement extends LitElement { static styles = css @property() name = 'World' render() { return html`<h1>Hello, ${this.name}!</h1>` } }
-
Run the esbuild script with Node.js >=16. You should be able to compile the component's styles successfully.
node ./esbuild.js
You can pass several options to the plugin, which by default reference those passed to esbuild.
Option | Type | Default |
---|---|---|
browserlistQuery | string | > 0.5%, last 2 versions, Firefox ESR, not dead . |
debug | boolean | The esbuild logLevel property is set to debug or false if not specified. |
includeDraftSpecs | boolean | Lightning CSS draft syntax transpilation is enabled by default. Set this property to true to include the draft specifications in the generated code. |
minify | boolean | The esbuild minify property or false if not specified. |
sourceMap | boolean | The esbuild sourceMap property or false if not specified. |
If you encounter type issues when importing a CSS file within TypeScript code, you can add this line to your tsconfig.json
file:
{
"compilerOptions": {
// ...
"types": ["@detra-lab/esbuild-plugin-lit-css/declarations"]
}
}
Alternatively, you can use a *.d.ts
file (e.g. esbuild-env.d.ts
), in the root of your project and use this syntax:
/// <reference types="@detra-lab/esbuild-plugin-lit-css/declarations" />
Help us keep the project open and inclusive. Please read and follow our Code of Conduct.
Read our contributing guide to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.