rollup-plugin-lit-css

6.0.1 verified Mon Apr 27 auth: no javascript

Rollup plugin to import CSS files as JavaScript tagged-template literal objects for LitElement, FAST, and other web component libraries. Current version 6.0.1, released August 2024. Includes support for minification via cssnano, custom template tag specifiers, and transform hooks for Sass/Less/PostCSS. Ships TypeScript types. Key differentiator: allows CSS-in-CSS workflow for Lit-based projects, vs alternatives like lit-css-loader (webpack) or esbuild-plugin-lit-css.

Common errors

error Error: Cannot find module 'rollup-plugin-lit-css' ↓

cause Missing dependency or using wrong import path (CJS vs ESM).

fix

Run npm install rollup-plugin-lit-css. Ensure Rollup is configured for ESM.

error TypeError: litcss is not a function ↓

cause CommonJS require() used with ESM-only package (v6+).

fix

Change to ESM import: import litcss from 'rollup-plugin-lit-css'.

error The requested module 'rollup-plugin-lit-css' does not provide an export named 'Options' ↓

cause Type `Options` renamed to `RollupPluginLitCssOptions` in v6.

fix

Use import type { RollupPluginLitCssOptions } from 'rollup-plugin-lit-css'.

Warnings

breaking v6 drops CommonJS support; package is ESM-only. ↓

fix Use ESM imports or switch to v5.x if CJS required.

deprecated The `options` export was removed; use `RollupPluginLitCssOptions` type. ↓

fix Replace `Options` with `RollupPluginLitCssOptions` in TypeScript definitions.

gotcha When using `specifier`, the package must export a `css` function. `@microsoft/fast-element` exports `css` as a named export. ↓

fix Ensure the specifier package's `css` function is compatible with tagged template literals.

gotcha CSS imports are default-exported as an object, not a string. Using `require()` will not work; must use `import`. ↓

fix Use `import style from './file.css'` syntax; do not use `require`.

gotcha The `transform` option must return a string, not a Buffer or object. Async transforms are supported. ↓

fix If using Sass, call `.css.toString()`. For PostCSS, access `.css` property.

Install

npm install rollup-plugin-lit-css

yarn add rollup-plugin-lit-css

pnpm add rollup-plugin-lit-css

Imports

default

wrong

const litcss = require('rollup-plugin-lit-css');

correct

import litcss from 'rollup-plugin-lit-css';

ESM-only since v6; no CommonJS support. Requires Rollup ESM config.

RollupPluginLitCssOptions

wrong

import { Options } from 'rollup-plugin-lit-css';

correct

import type { RollupPluginLitCssOptions } from 'rollup-plugin-lit-css';

TypeScript users must use the exact exported type name for options.

style (imported CSS file)
wrong
```
import { css } from './styles.css';
```
correct
```
import style from './styles.css';
```
CSS files are imported as default exports, not named exports. The plugin transforms CSS into a tagged template literal.

Quickstart

Minimal Rollup config and LitElement component showing CSS import via tagged template literal.

// rollup.config.js
import litcss from 'rollup-plugin-lit-css';

export default {
  input: 'src/index.js',
  output: { dir: 'dist', format: 'es' },
  plugins: [
    litcss({
      include: ['**/*.css'],
      cssnano: true, // minify output
    }),
  ],
};

// src/component.ts
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import style from './styles.css';

@customElement('my-component')
class MyComponent extends LitElement {
  static styles = [style];
  render() { return html`<p>Hello World</p>`; }
}