esbuild-plugin-lit-css

An esbuild plugin to transform a Lit component styles via Lightning CSS: an extremely fast CSS parser, bundler, transformer, and minifier.

Tested using esbuild v0.19 and v0.20.

• esbuild-plugin-lit-css
  • About Lightning CSS and the plugin
  • Installation and usage
  • Plugin options
  • TypeScript support
  • Code of Conduct
  • Contributing
  • License

About Lightning CSS and the plugin

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.

Installation and usage

1. Install the NPM package of the plugin, along with esbuild itself:

   pnpm add -D @detra-lab/esbuild-plugin-lit-css esbuild

2. 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()]
   })

3. 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>`
     }
   }

4. Run the esbuild script with Node.js >=16. You should be able to compile the component's styles successfully.

   node ./esbuild.js

Plugin options

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

TypeScript support

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" />

Code of Conduct

Help us keep the project open and inclusive. Please read and follow our Code of Conduct.

Contributing

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.

License

Apache License 2.0